Skip to content

Diagnostics

Every code runbook spec validate, runbook push and publishing can report. Each diagnostic names a path into your runbook (a JSON pointer such as /spec/steps/2/approval/options), a code and a message, and in --json output a line and column where it can:

$ runbook spec validate my-runbook.yaml
/spec/steps/0/actor: spec.invalid_value: spec.invalid_value

The quoted sentence under each code is the compiler’s message for it, which the web editor and the API show.

YAML syntax error in runbook source.

The file isn’t valid YAML: an indentation slip, an unclosed quote or bracket, or a tab used for indentation.

Fix: open the line and column the diagnostic names. Quote strings that contain : or start with {, [, * or &, and expressions such as "${{ inputs.x == 'a' }}".

Multiple YAML documents found; only single-document runbooks are supported.

The file has more than one YAML document (separated by ---).

Fix: keep one runbook per file.

Forbidden YAML feature (such as anchors, aliases, or merge keys) used in document.

The file uses anchors (&name), aliases (*name), merge keys (<<:) or custom tags, which runbooks don’t allow so that what you read is what runs.

Fix: write the repeated values out, or move them to spec.defaults.

YAML nesting depth exceeds the maximum limit.

The YAML nests deeper than the parser allows.

Fix: flatten the structure; deep nesting usually means a runaway generator.

Duplicate key found in mapping.

The same key appears twice in one mapping. YAML would silently keep the last one; runbooks refuse it.

Fix: remove or merge the duplicate.

Mapping keys must be strings.

A mapping key isn’t a string (for example 1: or true:).

Fix: quote the key.

Scalar value is not a valid JSON number or scalar.

A value can’t be represented in JSON, such as .nan, .inf or a YAML timestamp.

Fix: quote it as a string.

Document structure does not match the runbook schema.

The document isn’t a mapping with metadata and spec.

Fix: start from a sample or the shape in the language overview.

A required field is missing.

A required key is missing, such as metadata.id, spec.steps, a step’s id or an approval’s prompt.

Fix: add the key the diagnostic’s path names.

API version is not supported; use therunbook.app/v1.

apiVersion is set to something other than therunbook.app/v1.

Fix: use therunbook.app/v1, or leave apiVersion out.

Document kind is not supported; must be Runbook.

kind is set to something other than Runbook.

Fix: use Runbook, or leave kind out.

Unknown key is not recognized.

A key the language doesn’t have at that level: often a typo, or a key nested one level too deep or too shallow.

Fix: check the spelling and level against the key reference. Keep your own data under a key that starts with x-; those are kept and never executed.

This feature is not supported in this profile.

A key the language deliberately refuses, such as agent.runner, agent.model, agent.max_cost_usd or agent.max_tokens.

Fix: remove it. Limit what an agent can do through the access you give it, not through the runbook.

The value is not supported.

A value the language doesn’t support at that key, such as an evidence kind other than link, log, file or screenshot, or an unknown join.

Fix: use one of the values the key reference lists.

Data type is not supported.

A declaration’s type isn’t one of the supported types (for example secret_ref or float).

Fix: use string, text, number, integer, boolean, enum, multi_enum, list, object, date, datetime, duration, url, email or user.

The structure does not have the expected object or array shape.

A key has the wrong structure: an object where a list belongs, a wait with none or several of for, until and signal, a loop with both until and while, or fail_fast with a join other than all.

Fix: read the diagnostic’s message and path, and compare with the key’s example in the key reference.

The value has an invalid type.

A value has the wrong JSON type for its key: a string where a number is expected, a list where an object is.

Fix: give the type the key expects; quote numbers you mean as strings.

The value is not allowed here.

A value is out of its allowed set or range: an unknown actor or on_failure, a duration that doesn’t parse, an empty or duplicate approval option, a catch_up over 24 hours, a recipient that isn’t team:<slug>, user:<name> or a name.

Fix: use one of the documented values. Durations are digits and units, such as 90s, 15m, 2h, 1d or 1h30m.

Field is not valid for this step type.

A key that doesn’t belong on this kind of step, such as instructions on a parallel, actor on an approval or outputs on a group.

Fix: move the key to the step it belongs on, or turn the step into a task. Every step takes id, title, if, on_failure, timeout and labels.

Multiple conflicting control flow structures are defined on this step.

A step has more than one control key, such as both steps and parallel, or wait and approval.

Fix: split it into two steps, or nest one inside the other.

Invalid step labels.

A step’s labels aren’t a flat map of at most 16 strings with lowercase keys ([a-z0-9][a-z0-9_./-]*, at most 63 bytes) and values of at most 256 characters.

Fix: shorten or rename the labels; put structured data under an x- key.

An agent hint is given both under ‘agent’ and under ‘agent.hints’; give it once.

A hint is given both as agent.tools (or agent.commands) and under agent.hints.

Fix: keep one; agent.hints.tools is the current spelling.

Identifier contains invalid characters or has an invalid length.

An ID has the wrong form. A runbook ID is kebab case (lowercase letters and digits separated by single hyphens); a step or trigger ID is lowercase letters, digits and _, starting with a letter. Both are at most 63 bytes.

Fix: rename it, for example Check-Health to check_health for a step.

Duplicate step ID found in the runbook.

Two steps share an ID. IDs are unique across the whole runbook, including nested and finally steps.

Fix: rename one of them.

Duplicate trigger ID.

Two triggers share an ID; IDs are unique across schedule and webhook.

Fix: rename one of them.

Timeout setting is only supported on task steps.

timeout is set on a container, wait or approval step. A step’s timeout applies to tasks only.

Fix: put the timeout on the tasks inside, or use wait.timeout, approval.timeout or spec.execution.timeout.

Failure handoff is only supported on task steps.

on_failure: handoff is set on a step that isn’t a task.

Fix: set it on the tasks inside the container, or under spec.defaults.on_failure.

End steps are not permitted inside finally blocks.

An end step is inside a finally block, where the run is already ending.

Fix: remove it, or move it to the main steps or a catch.

catch_on needs a catch block on the same group.

catch_on is set on a group without a catch.

Fix: add the catch steps, or remove catch_on.

Wait outputs need a signal wait.

wait.outputs is set on a wait for a duration or a time. Only signals carry a payload.

Fix: remove outputs, or wait for a signal.

Invalid reminder or escalation settings.

The reminder or escalation keys don’t fit together: remind_every without remind_after, escalate_after without escalate_to (or the reverse), an empty escalate_to, or a zero duration.

Fix: give remind_after with remind_every, and escalate_after and escalate_to together.

assignment: strict is set on a task with no assignee to restrict to.

Fix: add an assignee, or remove assignment.

Loop alias collides with a reserved or existing name.

A foreach.as name shadows a name expressions already use: inputs, vars, fields, steps, outputs, index, iteration or an enclosing loop’s variable.

Fix: pick another name, such as region or host.

Control flow nesting exceeds the maximum allowed depth.

Containers nest deeper than 32 levels.

Fix: flatten the structure, or split part of it into another runbook and call it.

Schema declaration is invalid.

A declaration is malformed: an enum without options, items on something other than a list, properties on something other than an object, a default that doesn’t match its type, or min above max.

Fix: compare with the declaration examples in the key reference.

A pattern isn’t a valid regular expression in the supported dialect, which runs in linear time and has no backreferences or lookaround.

Fix: simplify the pattern; patterns already match the whole value, so ^ and $ aren’t needed.

A pattern is longer than 1,024 characters, or compiles too large.

Fix: shorten it, or check the value in a step instead.

Schema declaration nesting exceeds the maximum allowed depth.

Declarations nest deeper than 64 levels.

Fix: flatten the declared structure.

Schema declaration count exceeds the maximum limit.

More than 4,096 declarations in the runbook.

Fix: declare less structure; use object without properties details where you don’t need them checked.

The number of indexed fields exceeds the limit of 10.

More than 10 fields have indexed: true.

Fix: index only the fields you search runs by.

Referenced field is not defined.

A set.fields entry, or an expression, names a field spec.fields doesn’t declare.

Fix: declare the field, or correct its name.

Referenced variable is not declared.

A set.vars entry, or an expression, names a variable spec.vars doesn’t declare.

Fix: declare it under spec.vars with a starting value.

Circular dependency detected in variable declarations.

Variables’ starting values refer to each other in a loop (a uses b, b uses a).

Fix: give one of them a literal starting value.

Type cannot be inferred from null or an empty list.

A variable’s starting value is null or an empty list, so its type can’t be inferred.

Fix: give a starting value of the type you mean, such as "", 0 or a one-item list.

A required field is missing.

A value is missing a required property: an input at start, an output in a report, a property of an object.

Fix: supply the property the path names, or make it optional.

The value does not match the expected data type.

A value doesn’t match its declared type.

Fix: send the declared type; numbers you mean as text need quotes in YAML.

The value is not one of the allowed enum options.

A value isn’t one of the declaration’s options.

Fix: use one of the options, or add the value to them.

The numeric value is outside the allowed range.

A number, a string’s length or a list’s size is outside min and max.

Fix: adjust the value or the bounds.

A string doesn’t match its declaration’s pattern.

Fix: correct the value; remember the pattern must match the whole string.

A value isn’t in its type’s format: a date that isn’t YYYY-MM-DD, a datetime that isn’t RFC 3339, a url that isn’t an absolute http(s) URL, or an email, duration or user that doesn’t parse.

Fix: send the value in the type’s format.

Unknown field is not defined in the schema.

A value has a property its declaration doesn’t name. Declarations are closed.

Fix: remove the property, or declare it.

Data nesting exceeds the maximum allowed depth.

A value nests deeper than 64 levels.

Fix: flatten the value.

An expression inside ${{ … }} doesn’t parse.

Fix: check brackets and quotes. Use single quotes for strings inside an expression and double quotes around the whole YAML value: "${{ inputs.env == 'prod' }}".

The expression has the wrong type for where it is used.

An expression has the wrong type for where it’s used (a string where if needs a boolean, or two different types compared), or reads a name that isn’t in scope, such as a step that doesn’t exist or a loop variable outside its loop.

Fix: compare like with like, give if, when, until and while a boolean expression, and check the names it reads.

The expression uses something outside the runbook-cel/1 profile, such as arithmetic, string functions, list or map literals, or a macro other than one exists.

Fix: compute the value in a step and read its output, or use the operators the expressions page lists.

A value bound into an expression at run time can’t be represented, such as a timestamp outside the years 0001 to 9999.

Fix: check the input or output that feeds the expression.

The values bound into an expression at run time are larger than the profile allows.

Fix: read a smaller part of the data, such as one property instead of a whole object.

An expression is over 256 nodes or 32 levels deep, or its source is over 4,096 bytes.

Fix: simplify it, or split it across variables.

An expression would cost more than the profile’s evaluation budget.

Fix: simplify it; avoid exists over large lists.

An integer literal overflows, such as -(-9223372036854775808).

Fix: use a smaller literal.

Expression schema is invalid.

The types an expression can see (inputs, fields, steps and their outputs) couldn’t be assembled, usually because of a malformed declaration.

Fix: fix the declaration diagnostics first; this one usually follows from them.

Expression schema exceeds the maximum allowed types or fields.

The runbook has more than expressions can type: over 256 steps with IDs, over 256 declared outputs, or foreach and loop nested more than 4 deep.

Fix: split the runbook and call the parts, or flatten the loops.

Expression profile is not supported.

The runbook asks for an expression profile other than runbook-cel/1.

Fix: remove the profile setting.

Approval must specify at least one approver.

An approval names no approvers. Reported when you publish.

Fix: add approvers: { users: [...] } or approvers: { teams: [...] }.

Agent approvals require min to be set to 1.

allow_agents: true is set on an approval whose min isn’t 1.

Fix: set min: 1, or don’t let agents decide.

An approval that agents may decide leads to a destructive task; only people may approve that path.

An approval that agents may decide (allow_agents) can lead to a destructive task. Only people may approve a destructive path. Reported when you publish.

Fix: remove allow_agents, or put a human approval between this one and the destructive task.

Automatic timeout decision must name an option with auto: true.

on_timeout: { decide: … } names an option that doesn’t exist or isn’t marked auto: true.

Fix: mark the option auto: true, or name an option that is.

Automatic decision cannot reach a destructive task without allow_auto_decision.

An approval’s automatic timeout decision can lead to a destructive task that hasn’t opted in.

Fix: set allow_auto_decision: true on that task if an unattended decision may really trigger it; otherwise use on_timeout: escalate.

Escalation policy must specify at least one recipient.

An approval escalates at its timeout but there is no one to escalate to: no escalate_to and no metadata.owners.

Fix: add escalate_to, or owners to the runbook.

Setting on_timeout requires timeout to be specified.

on_timeout, escalate_to or escalation_timeout is set on an approval without a timeout.

Fix: add timeout, or remove the keys that depend on it.

Approval escalation must specify at least one user or team recipient.

An approval’s escalation resolved to no one when it fell due.

Fix: give the approval escalate_to recipients who exist, or owners to the runbook.

This step is not an approval step.

An approval action named a step that isn’t an approval.

Fix: use the step run ID of an approval step.

Invalid cron expression.

A schedule’s cron isn’t five valid fields.

Fix: use minute, hour, day of month, month and day of week, such as 0 2 * * * (02:00 daily) or */15 9-17 * * MON-FRI.

Unknown time zone.

A schedule’s timezone isn’t an IANA zone name.

Fix: use a name such as UTC, Europe/London or America/Los_Angeles, not an abbreviation such as PST.

Invalid trigger inputs.

A trigger’s inputs name an input the runbook doesn’t declare, give a value of the wrong type, or, on a schedule, leave out a required input that has no default.

Fix: match the runbook’s spec.inputs.

A trigger’s when must be true or false.

A webhook trigger’s when isn’t a boolean expression.

Fix: compare values: "${{ payload.status == 'success' }}".

A step cannot define both ‘skill’ and ‘skills’.

A step has both skill and skills.

Fix: use skills: [a, b] alone.

A step can define at most 8 skills.

A step attaches more than 8 skills.

Fix: attach the ones the step needs, or split the step.

A step cannot declare duplicate skills.

A step lists the same skill twice in skills.

Fix: remove the duplicate.

Skill reference could not be resolved in the skill catalog.

A skill alias isn’t declared in spec.skills, or (when you publish) no skill of that name has been uploaded to the project.

Fix: declare the alias, and upload the skill with runbook skill push <dir> --project <project>. Offline validation can’t check uploads; samples stop here for that reason.

The called runbook has no published version (or not the pinned version) in this project. Reported when you publish; offline validation can’t see your server.

Fix: publish the child runbook first, or correct its ID or version.

The runbook reaches itself through call, directly or through other runbooks.

Fix: break the cycle; put the shared steps in a third runbook both call.

Calls nest more than 3 deep (a run, its child, grandchild and great-grandchild).

Fix: flatten the chain.

call.with names an input the child doesn’t declare.

Fix: use the child’s input names.

call.with leaves out an input the child requires and has no default.

Fix: pass it in with.

A literal in call.with doesn’t match the child input’s type.

Fix: pass the child’s declared type.

call.outputs names an output the child doesn’t have.

Fix: use the child’s spec.outputs names.

call.outputs declares a type that doesn’t match the child’s output.

Fix: declare the type the child’s output has.

Team reference could not be resolved.

A team named in approvers, assignee, escalate_to or owners doesn’t exist on your server. Offline validation has no directory, so runbook spec validate always stops here when a runbook names a team.

Fix: create the team (runbook team create), or correct its slug.

User reference could not be resolved.

A user named in the runbook doesn’t exist on your server.

Fix: correct the name, or add the person.

The value exceeds the maximum allowed limit.

A bounded value is over its limit: more than 20 parallel branches, foreach.max_items over 100, loop.max_iterations over 50, a wait.for over 7 days, or more than 16 triggers of a kind.

Fix: lower the value, or split the work across runs.

Runbook exceeds the limit of 256 steps.

The runbook has more than 256 steps with IDs.

Fix: split it into runbooks joined with call.

Runbook source exceeds the size limit.

The source is larger than the server allows (1 MiB, or lower with RUNBOOK_MAX_SOURCE_BYTES).

Fix: split the runbook, or move long instructions into skills.

Total number of source values exceeds the maximum limit.

The source has more than 262,144 values.

Fix: split the runbook.

Cumulative source path bytes exceed the allowed budget.

The source’s paths together are too long (very deep or very wide data).

Fix: flatten long data under vars or with.

Compilation resource limit exceeded.

Compiling would use more resources than allowed, usually from many large expressions or declarations together.

Fix: split the runbook.

Compilation context exceeds the allowed size limit.

The directory context sent with a compile (teams, users, skills, called runbooks) is too large.

Fix: name fewer distinct teams, users and skills in one runbook.

Worst-case step budget calculation overflowed.

The worst-case number of step runs overflows; loops, foreach and retries multiply each other.

Fix: lower max_items, max_iterations or retry.max_attempts, or un-nest them.

Agent parameters exceed the allowed size limit.

spec.agents.params encodes to more than 4,096 bytes.

Fix: pass less, and let the launcher look the rest up.

Agent dispatch is no longer supported; use webhook subscriptions instead.

spec.agents.dispatch was removed.

Fix: subscribe a webhook to agent.work_available and put what the launcher needs in spec.agents.params; see webhooks.

These come from stored, compiled runbooks rather than from what you write. Seeing one usually means a stored version is damaged or was written by a different release.

Intermediate representation is invalid.

The compiled form failed its own consistency checks.

Fix: republish the runbook; if it persists, report it with the source.

Compiled snapshot is corrupted or invalid.

A stored compiled snapshot couldn’t be read.

Fix: republish the runbook.

Snapshot hash does not match the runbook source hash.

A stored snapshot doesn’t belong to the source it was stored with.

Fix: republish the runbook.

Snapshot step budget does not match the compiled runbook.

A stored snapshot’s step budget doesn’t match its compiled form.

Fix: republish the runbook.

Snapshot resource pins do not match the environment.

A stored snapshot’s pinned skills and called runbooks don’t match.

Fix: republish the runbook.

Compiled snapshot exceeds the size limit.

A compiled snapshot is larger than the server stores.

Fix: split the runbook.