Skip to content

Limits and errors

Every trulyform definition limit, how save errors differ from publish issues, the MCP error codes, and how to fix the most common problems.

View as Markdown

All docs pages
On this page

What you need to know

  • trulyform checks a form twice. Saving rejects a definition with the wrong shape and saves nothing. Publishing also requires the draft to have no issues.
  • A draft can be saved with issues, such as an untitled question, so you can build a form in several steps.
  • Every error names where the problem is: a path in the definition for save errors, a nodeId for publish issues.
  • The limits below are hard limits.

Limits

Limit Value Notes
definition_bytes 2,000,000 Maximum size of the whole definition as UTF-8 JSON.
fields 200 Questions per form.
options_per_field 250 Choices per question (matrix columns included).
rows_per_field 100 Rows per matrix question.
rules 300 Logic rules per form.
conditions_per_rule 20 Conditions per logic rule.
calculations 100 Calculations per form.
expression_depth 12 Nesting depth of one calculation expression.
calculation_name_length 100 Characters per calculation name.
hidden_fields 30 Hidden URL parameters captured per form.
text_length 10,000 Characters per rich-text text node.
label_length 2,000 Characters per choice or row label.
button_length 100 Characters per button label.
max_files_per_answer 10 Largest maxFiles setting. The respondent can upload no more than the form owner's plan allows: Free 1 file, Pro 10 files, Business 10 files.
max_file_megabytes 10 Largest file a respondent can upload, in MB, whatever maxSizeMB says.

Plan limits

Logic, calculations and every question type are available on every plan. These depend on the form owner's plan:

Plan Files per answer File storage Partial responses Customer logo
Free 1 10 MB No No
Pro 10 1 GB Yes No
Business 10 10 GB Yes Yes

Each person can make up to 120 MCP requests per minute.

Save errors

When the shape is wrong, save_form_draft returns validation_failed with an errors object that maps a path to its messages:

A save error

{
    "code": "validation_failed",
    "message": "Correct the indicated fields and try again.",
    "errors": { "fields.0.kind": ["The selected fields.0.kind is invalid."] }
}

Select the text to copy it.

Paths count from the definition: fields.0.kind is the kind of the first question. Paths of rich-text errors start with definition., such as definition.fields.0.title, and point at the same place. The error's docs list names the sections that explain it; pass one to read_docs.

Message Cause Fix
The selected fields.0.kind is invalid. Not one of the question types Use a kind from Question types.
The fields.0.id field must be a valid UUID. The ID is not a UUIDv7 Use a UUIDv7. See Identifiers.
The fields.0.id field must be lowercase. Upper-case letters in the ID Write IDs in lower case.
The fields.0.id field has a duplicate value. Two questions share an ID Give each one its own ID.
Every question, choice, row, rule, and calculation needs a unique identifier. An ID is used twice, for example by a choice and a question Use a fresh ID for each.
Use supported text formatting. A title or description is a string, or uses an unknown node or mark Write it as rich text.
Use paragraphs with inline text and answer references. Rich-text nodes in the wrong place, such as text directly in the doc Put text inside a paragraph inside the doc.
The fields.0.settings field must be an array. settings contains a key that is not a setting, such as options or required Remove the key. The allowed keys are in Settings.
The definition field must be an array. An unknown top-level key, such as pages Send only the top-level keys.
The fields.0.required field must be true or false. A string such as "true" Send a JSON boolean.
The theme.primary field format is invalid. A color that is not #RRGGBB Use a six-digit hex color, such as #2563eb.
Use a lowercase UUIDv7 asset identifier or null. An empty string as an asset ID Use null.
This form exceeds the 2 MB definition limit. Remove unused content and try again. The definition is larger than 2 MB Shorten text or remove questions.

Publish issues

issues appear in get_form, in every save_form_draft reply and, when publishing fails, in the publish_form error:

A publish error

{
    "code": "validation_failed",
    "message": "Resolve these issues before publishing.",
    "issues": [
        { "nodeId": "01990000-0000-7000-8000-000000000001", "path": "options", "message": "Add at least two choices.", "severity": "error" }
    ]
}

Select the text to copy it.

nodeId is the ID of a question, rule or calculation, or one of form, theme, welcome and ending. path says which part of it to fix.

Issue Fix
Add at least one question. Add a question to fields.
Write your question. Give the question a title.
Add at least two choices. Add options to the choice question.
Give every choice a label. Fill in every option's label.
Add a label for every matrix row. Add rows to the matrix and label each one.
Statements cannot require or collect answers. Set required to false and empty options and rows.
Give the next button a label. Give nextButton a non-blank label, or leave the setting out.
Use a welcome button label and a positive response limit. Fill in welcome.button, and set fillLimit to null or a number above 0.
Use a numeric choice score. Write score as a decimal string, such as "10" or "2.5".
Use whole-number scale limits with at most 11 choices. Use whole numbers for an opinion scale's min and max, at most 10 apart.
Minimum must not exceed maximum. Swap min and max.
Increase the contrast of form text in Design so everyone can read it. Use a darker foreground or lighter background. See Readable colors.
Increase the contrast of button text in Design so everyone can read it. Change buttonText or primary so they contrast at 4.5:1.
Choose a question and a target later in the form. A rule's sourceId must come before its targetId. See Logic rules.
Conditions must use an answer available before this rule runs. Base conditions on the rule's source question or earlier questions.
Choose an operator supported by this answer type. Use an operator the question type supports. See Conditions.
Set a comparison value. Add a value to the condition.
This condition references a choice that was removed. Choose an available answer. Use an option ID that still exists.
Name this calculation. Give the calculation a name.
This calculation has a missing reference or a circular dependency. Point every reference at an existing calculation, without loops. See Calculations.
Piped answers must come from an earlier question. Move the answer token after the question it shows, or pipe a different question. See Piped answers.

Range issues name the setting, for example "Set maxFiles between 1 and 10." Use a value inside the range in Settings.

Error codes

Every tool error carries a code and a message:

Code Meaning What to do
unauthenticated The connection is not signed in. Sign in again from the client.
organization_required The account has no organization. The person joins or creates one in trulyform.
validation_failed The input is invalid. errors or issues say why. Fix what they name, then retry.
draft_conflict The draft changed since the revision you sent, or a mutation_id was reused for different content. revision holds the current revision. Read the form again and reapply your change.
not_found No such form or response in this organization. Check the ID with list_forms or list_responses.
forbidden The person is not allowed to do this. Ask the person.
operation_failed Something unexpected went wrong. Read the form again before retrying a write.

Ready to build?
Connect your assistant.

Pick your assistant, sign in to trulyform, and ask for the form you need.

Choose your assistant