Error codes

Who this is for: people and AI assistants who got an error from Liitora and want to fix it.

Before you start: have the error code at hand. The app shows it under the message (Error code:), the API returns it as error.code, MCP tools return it as error.code, and run logs show it in square brackets at the end of a step’s error, for example [http_status].

Every error from Liitora has a stable code. Codes never change their meaning, so your scripts and your AI assistant can rely on them. Find your code below: each entry says what happened, why, and how to fix it.

Where errors come from

Where you see it	Shape	Codes
The app, the REST API (/api/v1)	{"error": {"code", "message", "how_to_fix", "findings", "permission", "link"}} with an HTTP status	API and MCP errors, activation checks, other preconditions
Sign-in problems on the API and MCP server	{"error": "<code>"} with status 401, 403 or 503	unauthorized, invalid_token, forbidden, temporarily_unavailable
MCP tools (your AI assistant)	a tool result with isError: true and {"error": {"code", "what_went_wrong", "how_to_fix", "docs", "findings", "link"}}	the same codes as the API, plus invalid_argument
A run: a step or the whole run failed	the run’s error and the step’s error in the run view and the run log	run and step errors, script errors, email errors
A webhook sender (the system calling your webhook URL)	{"error": {"code", "message"}} with an HTTP status	webhook delivery responses
Alerts and incidents	the alert email or message, and the incident	alerts

When you save a workflow, problems in the YAML come back as findings under validation_failed. Each finding has its own code, a line and column, what went wrong and how to fix it. See validation findings.

API and MCP errors

not_found

HTTP status: 404.

What happened: the workflow, run, secret, connection or other object does not exist.

Why: the id or name is wrong, the object was deleted, or it belongs to another company. Liitora answers the same way in all three cases, so nobody can find out what other companies have. A malformed id is also not_found.

How to fix: check the id or name. List the objects first (for example the Workflows page, or list_workflows for your AI assistant). If you have access to several companies, check that you signed in for the right one.

forbidden

HTTP status: 403. The error names the missing permission in permission.

What happened: you are signed in, but you may not do this.

Why: either your role does not include the permission (the message says “this needs the … permission”), or the action is reserved for people. Approving workflows, changing the activation policy, filling, setting, rotating, showing and deleting secrets, deleting webhook endpoints, email sender changes, API token management, company data exports and deleting the company can only be done by a signed-in person. AI assistants and API tokens are always refused, whatever their role (separation of duties). A read-only API token only gets the view permissions. Pointing a secret someone else saved at a connection needs reveal_secret, and changing where a production connection sends things needs approve_workflow, see who can change where a secret is sent.

How to fix: ask an admin for a role with the permission, see the permission list. If the action is for people only, do it yourself in the app. Your AI assistant gives you the link.

validation_failed

HTTP status: 422.

What happened: what you sent is not valid, so nothing was saved.

Why: the request breaks a rule. For workflows and actions, the error lists findings: each has a code, the place (path, line and column), what went wrong and how to fix it.

How to fix: fix every finding with severity error. Warnings do not block a save. Your AI assistant can check a workflow without saving it with validate_workflow. The codes are listed under validation findings.

conflict

HTTP status: 409.

What happened: the change clashed with another change.

Why: someone saved a newer version of the workflow while you were editing, an object with this name already exists, or the version is already approved.

How to fix: reload the object, apply your change to the newest version and save again. In the app, select Reload the latest version on the YAML tab. For a name clash, pick another name.

temporarily_unavailable

HTTP status: 503, with a Retry-After header.

What happened: a part of Liitora it needs (the database, the secret store or the test runner) did not answer.

Why: a short outage or a restart on our side. Nothing was changed.

How to fix: wait the number of seconds in Retry-After (usually 5) and try again. If it keeps happening, use Report a problem in the user menu (top right) in the app.

internal

HTTP status: 500.

What happened: something went wrong on our side. Nothing you sent caused it.

Why: a bug or an unexpected failure. The details are in our logs, not in the answer.

How to fix: try again in a moment. If it happens again, report it with the time it happened.

invalid_request

HTTP status: 400.

What happened: the request could not be read.

Why: the JSON is broken, a query parameter has a wrong value, or the body has a field Liitora does not know. Unknown fields are refused on purpose, so a typo never goes unnoticed.

How to fix: read the message: it names the problem. Check the field names against the API description at /api/v1/openapi.json.

payload_too_large

HTTP status: 413.

What happened: the request body is too large.

Why: API requests can be at most 2 MiB. Webhook deliveries can be at most 256 KB, or less if the endpoint has a lower limit.

How to fix: send a smaller body. For webhooks, ask the sender to send less, for example only ids, and fetch the details in a step.

unsupported_media_type

HTTP status: 415.

What happened: the body has a content type Liitora does not accept.

Why: the API takes application/json (and application/yaml for workflows). Webhooks take JSON, application/x-www-form-urlencoded, text/plain, text/csv and XML.

How to fix: send the right Content-Type header.

unauthorized

HTTP status: 401, with WWW-Authenticate: Bearer.

What happened: the request has no access token. For webhooks, the delivery was not accepted.

Why: on the API and MCP server, the Authorization: Bearer ... header is missing or uses another scheme. On a webhook URL, one answer covers every refusal: an unknown, paused or blocked URL, a sender address that is not allowed, and a missing or wrong signature, token or password. Liitora never says which, so nobody can probe your endpoints.

How to fix: on the API, send Authorization: Bearer <token>. For webhooks, see Webhook returns 401.

invalid_token

HTTP status: 401, with WWW-Authenticate: Bearer error="invalid_token".

What happened: the access token was refused.

Why: the token is expired, revoked, malformed or not meant for Liitora, your company is suspended, or your membership was removed. For API tokens: the token was revoked, has expired, is used from an address outside its allowed list, or the person who created it no longer has a role in the company. Liitora does not say which check failed.

How to fix: sign in again, or create a new API token (Settings, API tokens). Check the token’s expiry date and its allowed addresses. MCP clients that get this answer read the resource_metadata address in the challenge to sign in again.

invalid_argument

Where: MCP tools only. There is no HTTP status: the tool result has isError: true.

What happened: the tool got an argument it cannot use.

Why: a value has the right type but the wrong content, for example an unknown mode or a missing field that depends on another one. Arguments of the wrong type are refused by the MCP client library before the tool runs.

How to fix: your AI assistant reads how_to_fix and calls the tool again. The MCP tools reference lists every argument.

Members and invites

last_admin

What happened: you tried to give the only admin another role, or to remove them.

Why: a company always keeps at least one admin, so someone can still manage access and approve.

How to fix: make another member an admin first, then change or remove this person.

invite_used

What happened: the invite link was already used, or an admin cancelled it or sent a newer one.

Why: each invite link works once.

How to fix: ask an admin of the company to invite you again.

invite_expired

What happened: the invite link is more than 7 days old.

Why: invite links expire so an old email can’t be used to join later.

How to fix: ask an admin of the company to send you a new invite.

invite_other_workspace

What happened: the invited email already signs in to another company in Liitora.

Why: for now each person belongs to one company.

How to fix: ask to be invited with another email address.

invite_sign_in_required

What happened: you tried to accept an invite for an email that already has a Liitora account, without signing in.

Why: an invite for an existing account can only be accepted by that account, so nobody else can take it.

How to fix: on the invite page, select Sign in to accept, sign in with the account for the invited email, then select Accept the invite.

invite_wrong_account

What happened: you are signed in with a different account than the one the invite was sent to.

Why: an invite for an existing account can only be accepted by that account.

How to fix: select Sign out on the invite page, then sign in with the account for the invited email. If you don’t have it, ask an admin to invite the email you use.

invite_email_unverified

What happened: the account for the invited email hasn’t confirmed its email address.

Why: Liitora only gives access to an account whose email is confirmed, so an invite can’t be taken by someone who only typed the address.

How to fix: ask an admin of the company to invite you with another email address, or report a problem.

email_not_configured

What happened: Liitora could not send the invite because its email sending is not set up.

Why: the invite link is only ever sent by email.

How to fix: try again later, and report a problem if it keeps happening.

Activation checks

These codes block activation. Liitora checks them in this order and answers with the first one that fails (HTTP 409). The Overview tab of a workflow shows all of them at once under Before it can be activated, see the workflow page. Your AI assistant gets the same list from get_workflow.

archived

HTTP status: 409.

What happened: the workflow is archived, so it cannot be activated, run or changed. Its runs cannot run again either, and a production run that was still waiting to start stops before its first step.

Why: someone selected Archive. Archiving is for good.

How to fix: create a new workflow from the archived one’s YAML. The old history stays.

capabilities_unknown

HTTP status: 409.

What happened: “This workflow version doesn’t record which secrets and connections it may use, so it can’t run. Save the workflow again to make a new version.”

Why: every version records exactly which secrets and connections its runs may use. A version saved before Liitora did this gets the list from its saved checks. When that isn’t possible, the version is kept safe: it can’t be activated, and a run of it fails with this code before any step starts.

How to fix: save the workflow again (no change is needed). Under the default policy a person then approves the new version before it can be activated. See Why names must be literal.

missing_actions

HTTP status: 409.

What happened: the workflow uses an action or another workflow that does not exist.

Why: a uses: line points at an action of your library, the platform library or another workflow that was never created, was named differently, or has no release that matches the version.

How to fix: create or fork the missing action, or fix the uses: reference. Then save a new version so its inputs are checked against the action. An action created after the save still needs this new version: only a saved version records which version of the action runs.

connection_missing

HTTP status: 409. Links to the Connections page.

What happened: a connection the workflow uses does not exist in the production environment.

Why: activation runs the workflow in production, so every name under connections: needs a production setup. A test setup alone is not enough.

How to fix: on the Connections page, set up the connection for Production with the same name. See Create a connection.

secret_missing

HTTP status: 409 on activation. Also a step error in a run.

What happened: a secret the workflow or its connections need does not exist.

Why: a script reads a secret with ctx.secrets.get("name"), or a connection names a secret, but no secret with that name was ever requested or added. In a run, the step could not find the value when it needed it, for example because the secret was deleted.

How to fix: add the secret on the Secrets page, or ask your AI assistant to request it and fill it in through the link. See Add a secret and the troubleshooting steps.

secret_requested

HTTP status: 409.

What happened: a secret was asked for, but nobody has added its value yet.

Why: your AI assistant (or a colleague) requested the secret. Only a person can add the value. The same code also answers when you try to show a secret that has no value yet, or the signing secret of a Stripe webhook endpoint nobody has pasted yet.

How to fix: open the fill link your assistant showed you, or open Secrets and use Add the value under Waiting for you. See Add a secret from a link.

secret_expired

HTTP status: 409.

What happened: a secret the workflow needs has passed its expiry date.

Why: the secret was saved with an Expires on date, and that date has passed. Liitora marks it expired and sends a reminder with a link.

How to fix: rotate the secret with a new value. See Rotate and expire secrets.

tests_not_run

HTTP status: 409.

What happened: this version has no test results.

Why: the version has no test cases, or its tests have not run yet on this exact version.

How to fix: add test cases (a happy path, an upstream failure, an empty case and, for webhook workflows, a malformed payload) and save a new version. Tests run on every save. You can also select Run tests on the Tests tab. See Read and write workflow tests.

tests_failed

HTTP status: 409.

What happened: the tests did not pass on this version, or a required kind of test case is missing.

Why: at least one case failed or could not run, the test fixtures contain something that looks like a real credential, or the required minimum is not met. The message names the failed cases and the missing kinds.

How to fix: open the Tests tab. Each check is a sentence with the expected and the actual value. Fix the workflow or the case and save a new version. See the troubleshooting steps.

ai_disabled

HTTP status: 409. Links to Settings. Also a run and step error.

What happened: this workflow uses AI, and AI is turned off for your company. It can’t be activated, started, retried or replayed. A run that was already waiting fails before its first step, and any call to an AI model fails.

Why: an admin turned off Allow AI steps in Settings, Members, under AI.

How to fix: ask an admin to turn AI back on, or remove the AI steps and save a new version. See AI in workflows.

ai_strict_mode

HTTP status: 409. Links to Settings.

What happened: an AI answer decides where data goes or what is changed in this workflow, and your company has strict mode on. The version can’t be approved or activated.

Why: in strict mode an AI answer may only pick from a fixed list that you wrote. It may not decide a recipient, an address, a file path or another write target on its own.

How to fix: limit the AI answer to a fixed list of choices (enum in the output_schema), or take the target from somewhere other than the AI answer, and save a new version. An admin can also turn strict mode off. See AI in workflows.

approval_required

HTTP status: 409. Links to the Approve and activate page.

What happened: a person must approve this version before it can be activated.

Why: the workflow uses the default policy, “A person approves each version”. Either nobody has approved this version yet, or an AI assistant tried to activate it. AI assistants never activate under this policy.

How to fix: open the link, check what the version does, and select Approve this version, then Activate. The approver needs the Approve workflows permission and cannot be the author. See Approve a workflow.

Other preconditions

These codes mean the object is not in a state that allows what you asked for. They all use HTTP 409.

ai_disclaimer_unconfirmed

What happened: you tried to approve a version that uses AI without ticking the AI confirmation.

Why: AI answers can differ between runs, and the data the workflow reads can influence them. The approver confirms they have read what the AI steps send and to which provider. The confirmation is recorded in the audit log.

How to fix: on the approval page, read AI in this workflow and tick “I have read this and confirm the AI use”. Over the API, send confirm_ai: true with the approval.

ai_target_flows_unconfirmed

What happened: you tried to approve a version where an AI answer decides what is sent or changed, without confirming it.

Why: an AI answer that picks a recipient, an address or a record could send data to the wrong place. The approver confirms this on purpose, and it is recorded in the audit log.

How to fix: on the approval page, check the list under AI answers that decide what is sent or changed and tick the confirmation below it. Over the API, send confirm_ai_target_flows: true with confirm_ai: true. Or limit the AI answer to a fixed list of choices and save a new version.

author_cannot_approve

What happened: you tried to approve a version you wrote.

Why: your company has more than one approver, and a version you wrote yourself needs someone else to approve it (separation of duties). Versions your AI assistant or an API token made are different: you may approve those, unless your company requires a second approver.

How to fix: ask another person with the Approve workflows permission to review and approve it.

definition_mismatch

What happened: an approval sent through the API named a version, but the definition_hash it sent belongs to different content.

Why: the hash lets your script approve only the exact definition it checked. A different hash means it checked another version, so nothing was approved.

How to fix: fetch the version again (GET /api/v1/workflows/{id}?version=<number>), review it, and send its definition_hash with the same version_no. You can also leave the hash out: version_no alone names one fixed version.

self_approval_unconfirmed

What happened: you are the only approver, and you tried to approve a version you wrote, or your own library request, without confirming.

Why: approving your own change is allowed only when you say so on purpose. It is recorded in the audit log.

How to fix: tick “You are the only approver. Approve your own change?” on the approval page, or send confirm_self_approval: true with the approval.

requester_cannot_approve

What happened: you tried to approve a library request that you made, or that your AI assistant or your API token made for you.

Why: taking a library workflow into use takes two people. Your company has more than one person who can approve workflows, so another of them decides.

How to fix: ask another person with the Approve workflows permission to open the request in Workflow library and approve it. You can still reject your own request to withdraw it. See Take a library workflow into use.

item_flagged

What happened: you asked for, or tried to approve, a library workflow version that Liitora has flagged.

Why: Liitora found a problem with that version. A flagged version takes no new requests and can’t be copied. The message gives the reason.

How to fix: pick another version of the workflow, usually the newest one the library lists, or another workflow. Pause copies your company already made from the flagged version. See If Liitora flags a version you use.

item_not_in_use

What happened: you asked to compare a library workflow with the version your company uses, but your company has no approved copy of it.

Why: Liitora compares a newer version with the one you copied. Without a copy there is nothing to compare with.

How to fix: name the version to compare from with from, or read the workflow’s page as it is. See Updates.

item_not_verified

What happened: you tried to approve a library request, but the version it asks for no longer passes its signature or content hash check.

Why: Liitora checks the signature and the content hash again right before it copies a library workflow, and copies nothing it can’t vouch for. This can happen after Liitora replaces its signing key.

How to fix: reject the request, and ask again for the version the library lists now.

second_approver_required

What happened: you tried to approve a version you wrote, or one your AI assistant or your API token made for you, and your company requires a second approver. For a library request: you asked for it yourself, and either your company requires a second approver or the workflow isn’t published by Liitora.

Why: the require second approver setting is on, so nobody approves their own work. Work an assistant or a token did for you counts as yours here.

How to fix: invite another admin to approve it, or ask an admin to turn the setting off.

export_running

What happened: you tried to start a full export of your company’s data while another one is still waiting or being built.

Why: one export is built at a time in each company, so exports don’t slow each other down or use up the daily limit by accident.

How to fix: wait until the export in Settings > Export data is ready, then download it or start a new one. See Download a full export.

export_not_ready

What happened: you tried to download a full export that is still being built.

Why: the zip file only exists once the export is finished.

How to fix: wait until its status is Ready. The list on Settings > Export data refreshes by itself, usually within a few minutes.

export_failed

What happened: you tried to download a full export that failed, so there is nothing to download.

Why: the export grew larger than the limit, stopped before it was finished, or the person who started it can no longer export company data. The export’s message in the list says which.

How to fix: start a new export. If it grew too large, start it without run logs, or report a problem and we will help.

export_expired

What happened: you tried to download a full export more than 24 hours after it was ready.

Why: a ready export can be downloaded for 24 hours. After that its file is deleted, so a copy of your data doesn’t stay around longer than needed.

How to fix: start a new export on Settings > Export data.

confirmation_mismatch

What happened: you asked to delete your company, but the name you typed is not the company’s name.

Why: deleting a company cannot be undone, so Liitora asks you to type its name exactly as a last check. Spaces before and after the name are ignored, but upper and lower case count.

How to fix: type the name shown on Settings > Delete company exactly. See Delete your company.

deletion_scheduled

What happened: you asked to delete your company, but its deletion is already scheduled.

Why: a company is deleted once. The first request already stopped the company, and the erase follows after the waiting period.

How to fix: nothing to do. If the deletion was a mistake, tell us within the waiting period. See What happens next.

company_deleted

What happened: something tried to start new work, such as a run or an export, in a company that is being deleted.

Why: from the moment an admin asks to delete the company, nothing new starts there, so nothing is added while its data is being erased.

How to fix: nothing to do. If the deletion was a mistake, tell us within the waiting period. See Delete your company.

paused_by_system

What happened: you tried to resume a workflow that Liitora paused.

Why: the workflow was paused because of billing or because a plan limit was reached. Only a manual pause can be lifted by hand.

How to fix: solve the billing issue or wait for the limit to reset. The workflow resumes by itself. See Understand usage and limits.

not_active

What happened: the workflow is not active.

Why: you tried to start a production run (Run now) of a workflow that was never activated, or to pause a workflow that is not active.

How to fix: use Test run to try it, or activate it first.

test_run_in_production

What happened: a test run was started in the production environment.

Why: a test run can run any version, including one nobody has approved. So it never uses your production connections or changes anything in production, not even as a dry run. Through the API or an assistant this happens when is_test is sent without environment: test.

How to fix: start it in the test environment (environment: test), which uses your test connections. To see real production data without changing anything, start a dry run (dry_run: true) without is_test instead.

version_not_approved

What happened: a production run didn’t start, because its workflow version isn’t approved for production.

Why: production runs only run the version you activated, or another version that passed its tests and was approved. The run was refused before any step ran, and the refusal is in the audit log.

How to fix: approve and activate the version you want to run, then start the run again. To try an unapproved version, use Test run.

version_not_released

What happened: you tried to run a production run again (Run again, Retry from this step, or a dead letter replay), but it used an older version of the workflow.

Why: a newer version is live now. A production run always uses the live version, so an older version never changes anything in production again, even if it was approved once. A dead letter replay skips such runs and lists them with this code.

How to fix: start a new run with Run now, which uses the live version. To see what the older version does, start a Test run of it, which uses your test connections.

workflow_paused

What happened: you tried to start a production run of a paused workflow, or to run a production run again (Run again, Retry from this step, or a dead letter replay). Or a production run that was waiting to start found the workflow paused.

Why: a paused workflow starts no production runs. A run that was already waiting stops before its first step. A run that had already started a step finishes.

How to fix: select Resume first, then start or replay the run again. You can also use Test run, which uses your test connections.

manual_start_not_allowed

What happened: the workflow can’t be started by hand.

Why: its active version has no manual: true under on:, so Run now is turned off for it.

How to fix: add manual: true under on:, save, and activate the new version. A Test run works without it.

run_limit_reached

What happened: the run was not started, because your company has used all the runs included in its plan this month.

Why: Run now, the API, AI assistants, replays and retries use the same monthly run limit as schedules. Test runs and dry runs don’t count.

How to fix: runs start again on the first day of next month (UTC); the message says the date. To start them sooner, an admin changes the plan. See Understand usage and limits.

api_start_not_allowed

What happened: the workflow can’t be started through the API.

Why: its active version has no api: true under on:. Production runs started with an API token or by an AI assistant need it.

How to fix: add api: true under on:, save, and activate the new version. Test runs and dry runs work without it.

workflow_not_active

Where: a step error in a run.

What happened: a step calls another workflow (uses: workflow/...) that is not active: it was never activated, it is paused, or it is archived.

Why: production runs only call active, released workflows, so an unapproved or paused workflow never runs in production through a call.

How to fix: activate the called workflow, or resume it if it is paused.

link_expired

What happened: the secret fill link has expired.

Why: fill links work for 7 days.

How to fix: ask your AI assistant for a new link (it calls request_secret again), or add the value on the Secrets page.

already_set

What happened: the secret behind this fill link already has a value.

Why: someone filled it in already. A fill link never overwrites a value.

How to fix: nothing to do. To change the value, rotate it on the Secrets page.

secret_already_set

What happened: your AI assistant or an API token asked for a fill link for a secret that already has a value.

Why: a fill link for a saved value could get someone to overwrite a working credential, so only a person changes a saved value.

How to fix: nothing to do if the saved value is right: the workflow can use it as it is. To change it, rotate it on the Secrets page.

value_missing

What happened: the secret is marked as set, but the secret store has no value for it.

Why: the value was lost or removed from the store, for example after a restore.

How to fix: add the value again on the Secrets page with Rotate.

secret_in_use

What happened: you tried to delete a secret that a webhook endpoint still signs with.

Why: deleting it would break the endpoint.

How to fix: delete the webhook endpoint first. Its signing secret is removed with it.

fork_required

What happened: you tried to publish a new version of an action from the platform library.

Why: platform actions belong to Liitora and cannot be changed.

How to fix: fork the action into your own library (Fork into our library in the Library, or fork_action) and change the fork.

major_version_required

Where: a finding under validation_failed (HTTP 422) when you publish an action version.

What happened: the new version breaks the action’s contract, but its major version number is the same.

Why: workflows pinned to @v1 must keep working. A new required input, a removed or narrowed input, a removed or widened output, an output that is now optional, or a new required, removed or retyped connection slot is a breaking change. The message lists them. See Publishing a new version for the full list.

How to fix: publish it as the next major version (for example 2.0.0), or make the change backwards compatible.

schema_too_large

Where: a finding under validation_failed (HTTP 422) when you publish an action version.

What happened: the input or output schema is bigger than 64 KiB.

Why: every run checks data against the schema, so its size is limited.

How to fix: remove long descriptions and examples, or share repeated parts with $defs and $ref.

schema_too_deep

Where: a finding under validation_failed (HTTP 422) when you publish an action version.

What happened: the schema nests objects and arrays too deeply (more than 32 levels of JSON).

Why: very deep schemas are slow to check and hard to read.

How to fix: flatten the structure, or move nested parts into $defs.

schema_too_complex

Where: a finding under validation_failed (HTTP 422) when you publish an action version.

What happened: with every $ref written out, the schema would grow past 20,000 parts.

Why: references that point at references that point at references can multiply a small schema into a huge one, which would slow every run down.

How to fix: use fewer layers of references, or describe the data with fewer parts.

schema_recursive_ref

Where: a finding under validation_failed (HTTP 422) when you publish an action version.

What happened: a $ref in the schema points back to itself, directly or through other references.

Why: recursive schemas cannot be checked in bounded time, so they are not accepted.

How to fix: describe a fixed number of levels instead, or accept the nested part as a plain object.

schema_unsupported_ref

Where: a finding under validation_failed (HTTP 422) when you publish an action version.

What happened: the schema uses a $ref that points outside the schema, or one that is not supported ($dynamicRef, $recursiveRef), or one that points to nothing.

Why: schemas are checked without any network access, so every reference must point inside the same schema.

How to fix: copy the referenced part into $defs and point to it with "$ref": "#/$defs/name".

connection_in_use

What happened: you tried to delete a connection that a workflow still uses.

Why: deleting it would make those workflows fail.

How to fix: remove the connection from the workflows the message names, or archive them, then delete the connection.

secret_used_in_other_environment

What happened: a connection named a secret that a connection in the other environment already uses.

Why: test runs must never get production credentials. So a test connection can’t use a production connection’s secret, and a production connection can’t use a test connection’s secret.

How to fix: create a separate secret for each environment, with test credentials for the test connection and production credentials for the production one. See Test and production settings.

connection_shared_with_test

What happened: you tried to add test settings to a connection whose production settings are marked No separate test system.

Why: while that is on, test runs use the production settings, so there is nowhere for test settings to go.

How to fix: on the Connections page, select Use separate test settings on the connection, then add the test settings.

connection_has_test_settings

What happened: you tried to mark a connection as having no separate test system, but it already has test settings.

Why: test runs already use those test settings. Using production as well would only add risk.

How to fix: keep the test settings. If the system really has no test copy, delete the test settings first.

certificate_not_accepted

What happened: you tried to switch a Microsoft 365 connection to another certificate, and Microsoft refused the sign-in with it.

Why: Liitora signs in with the new certificate before it switches, so a certificate that isn’t in your app registration yet can never break the connection. Nothing changed: the connection keeps its current certificate.

How to fix: download the certificate, upload it to your app registration under Certificates & secrets, then Certificates, wait a few minutes and try again. See Connect Microsoft 365.

certificate_in_use

What happened: you tried to remove the certificate that a connection signs in with, while it has another certificate.

Why: removing it would stop the connection from signing in, even though the other certificate is ready.

How to fix: switch to the other certificate first with Use this certificate, then remove the old one.

oauth_state_invalid

What happened: the sign-in link you came back with is not valid. It was already used, it is older than 10 minutes, someone else started it, it belongs to another company, or the connection’s address, token URL or secrets changed after you selected Connect (also while Liitora was finishing the sign-in).

Why: each Connect sign-in works once, only for the person who started it, and only for a short time. If someone else tries to finish your sign-in, they are refused and your link keeps working for you.

How to fix: select Connect on the connection again.

destinations_changed

What happened: you saved a secret value from its fill page, but a connection that uses the secret got a new address, host or token URL while the page was open. Nothing was saved.

Why: you should only ever enter a value for the hosts you saw on the page.

How to fix: reload the page, check the hosts listed under Liitora sends this value only to, and save again. If a host looks wrong, don’t save: ask whoever made the connection.

oauth_denied

What happened: the other system did not allow the sign-in, for example because you selected Cancel or Deny there.

Why: Liitora gets access only when you allow it.

How to fix: select Connect again and allow access. If it keeps happening, ask the other system’s admin whether your account may use the app.

oauth_exchange_failed

What happened: the other system did not accept the sign-in when Liitora asked for the tokens.

Why: the token URL, the client ID or the client secret may be wrong, or the other system could not be reached.

How to fix: check the connection’s Token URL and its OAuth client secret, then select Connect again.

oauth_no_refresh_token

What happened: the other system signed you in but sent no refresh token.

Why: without a refresh token Liitora cannot keep the connection working on its own, so it stored nothing.

How to fix: allow offline access for the app in the other system, often with the offline_access scope, then select Connect again.

webhook_endpoint_limit

HTTP status: 409.

What happened: you tried to add a webhook endpoint, but your company already has as many as its plan allows.

Why: each plan allows a number of webhook endpoints (webhook_endpoints, see Limits per plan). Every endpoint is a public URL with its own delivery limit, so the number is capped.

How to fix: delete an endpoint you no longer use on the Webhooks page, or ask the account owner about a larger plan.

endpoint_in_use

What happened: you tried to delete a webhook endpoint that a trigger still uses.

Why: a workflow listens on it.

How to fix: remove the on.webhook trigger from the workflow first, then delete the endpoint.

provider_managed_secret

What happened: you tried to rotate the signing secret of a Stripe endpoint.

Why: Stripe creates that secret, not Liitora.

How to fix: roll the secret in the Stripe Dashboard, then paste the new one on the Secrets page. See Rotate webhook secrets.

not_supported

What happened: Test connection cannot test this connection.

Why: connections that sign in with a client certificate (mTLS) cannot be tested yet.

How to fix: use another sign-in method for now.

run_not_finished

What happened: you tried to retry, run again, replay quarantined items or save as a test a run that is still running.

Why: Retry from this step, Run again, Replay of quarantined items and Save as test need a finished run.

How to fix: wait until it finishes, or cancel it first.

nothing_quarantined

What happened: you asked to replay quarantined items, but the run has none.

Why: only items of a for-each step with strategy.quarantine: true that kept failing are quarantined.

How to fix: to run a step again, use Retry from this step instead.

item_replay_in_progress

What happened: the items you asked to replay are already being replayed.

Why: a replay run for them is queued or running. An item is never replayed twice at the same time.

How to fix: wait until that replay run finishes. If it does not fix an item, the item waits again and you can replay it then.

already_replayed

What happened: you asked to replay items that a replay already processed successfully.

Why: an item that was replayed successfully is done and is not replayed again.

How to fix: nothing to do. To process the data again, start a new run.

run_data_removed

What happened: you tried to run an old run again, retry it from a step, or save it as a test.

Why: the run finished longer ago than your plan’s log retention, so Liitora removed its input, its step inputs and outputs, its error messages and its result. Without them there is nothing to run again or test. The run’s status, times and error codes stay in the run history.

How to fix: start a new run with new input. To keep a case for testing, save a newer run as a test before its retention period ends. See Limits per plan for your plan’s retention.

run_not_testable

What happened: you tried to save a cancelled run as a test.

Why: a cancelled run stopped before it finished its work, so there is no outcome for a test to check.

How to fix: pick a run that succeeded, failed or was skipped.

run_too_large_for_test

What happened: a test case made from this run would be larger than one case may be (128 KiB).

Why: the run’s trigger input or the answers it got from other systems are large. Test cases are kept small so that they stay readable and fast.

How to fix: write the case by hand on the workflow’s Tests tab, with a smaller example input and only the mocks it needs.

production_run_needs_review

What happened: an assistant or agent asked to turn a production run into a test case.

Why: a production run holds real data, which can include personal data. A person must review that data before it is saved in a test.

How to fix: open the run in the web app and choose Save as test, or save a test run as a test instead.

artifact_too_large

HTTP status: 409 for a download. Also a step error in a run.

What happened: a file (artifact) is too large.

Why: downloads from the run view are limited to 25 MiB. In a run, a step made a file larger than your plan allows, or the run’s files together passed the run’s limit. A zip file that unpacks to too much is a format_error instead.

How to fix: split the file in the workflow, or send it as an email attachment instead. In a run, make the file smaller, for example by filtering rows, or store fewer files. See Work with files in a run.

operator_session_required

What happened: a Liitora operator tried to read your company’s usage without an open support session.

Why: our staff can only look into a company through a session with a written reason, and every look is recorded in your audit log.

How to fix: this concerns our operators only. See What “managed by us” means.

platform_sender_unavailable

What happened: the Liitora default email sender cannot be added.

Why: this Liitora installation has no default email domain set up.

How to fix: add an SMTP or Microsoft 365 sender instead. See Set up email senders.

not_allowed

What happened: the change is not allowed in the object’s current state.

Why: a rule in the database refused it, for example a workflow link that would create a cycle between workflows, or a change to a workflow that has no active version. The message says which rule.

How to fix: read the message and change what it names.

Run and step errors

A failed step shows its code in the run view and in the run log. The run itself then fails with step_failed. Steps with a retry: policy are tried again first when the failure is retryable (HTTP 429 and 5xx, timeouts and network errors).

step_failed

What happened: a step failed, so the run failed. The message names the step and ends with the step’s own code in square brackets.

Why: see the step’s code. For a built-in action it can also mean the action itself decided to fail, for example evaluate with fail_if_false: true whose check was false.

How to fix: open the run, expand the failed step and read its error and its HTTP calls. Fix the cause, then select Retry from this step. See Read run logs.

http_status

What happened: the other system answered with an HTTP status the step does not accept, for example 401, 404 or 500.

Why: http.request fails on any status outside 2xx, unless you list the accepted statuses in expect_status. 429 and 5xx are retryable.

How to fix: open the step’s HTTP calls to see the status. For 401 or 403, see A connection returns 401. For 404, check the path. For 429 and 5xx, add a retry: policy.

http_blocked

What happened: Liitora refused to send the request.

Why: the address is not allowed. Requests must use https://, must not contain a user name or password, and must go to a public internet address. Private, loopback, link-local and other internal addresses are always blocked, even when a public name points to them. So are names that only exist inside a network, such as localhost, erp or db.internal. For these the message is “This address points to a private network, which Liitora can’t reach.” Redirects to another host, hosts outside a connection’s allowed hosts and unsafe paths (..) are refused too.

How to fix: see Private address blocked.

http_too_large

What happened: a request or a response was too large.

Why: request and response bodies can be at most 10 MiB, and response headers at most 64 KiB.

How to fix: fetch less at a time, for example with paging.

http_failed

What happened: the HTTP request did not complete.

Why: the name could not be resolved, the connection failed, or the answer was broken. A firewall that does not know Liitora’s address can also drop the connection. The message “Outbound connections to port N are not allowed” means the system uses a port Liitora does not connect to (only 443, 22, 465 and 587).

How to fix: check the address. If your firewall only lets in known addresses, allow Liitora through it. If the other system was down, retry the run.

http_timeout

What happened: the other system did not answer in time.

Why: http.request waits 30 seconds by default (timeout_seconds, at most 300). Timeouts are retryable.

How to fix: add a retry: policy, raise timeout_seconds, or ask for less data per request.

secret_not_declared

What happened: “This workflow didn’t declare the secret X. Add it to the workflow and save it as a new version.”

Why: a run can only read the secrets its approved version declared, and each step only the ones its own script or action declared. An approver always knows what a workflow can use. Here a step asked for a secret that isn’t in its list, for example a secret that only another step of the workflow uses. Liitora gives the same answer whether or not the secret exists.

The whole run stops at this point. The script can’t catch this error, no other step starts, and the run isn’t retried. The attempt is recorded once in the audit log.

How to fix: write the name literally in the script of the step that needs it, for example ctx.secrets.get("erp_key"), and save the workflow. Production runs use the new version once it is approved and activated. See Why names must be literal.

connection_not_declared

What happened: “This workflow didn’t declare the connection X. Add it to the workflow and save it as a new version.”

Why: a run can only use the connections its approved version declared, and each step only the ones under its own connections:. The whole run stops at this point, like with secret_not_declared, and the attempt is recorded once in the audit log. A poll trigger stops checking with this code when its connection isn’t in the version it belongs to.

How to fix: add the connection to the step that uses it under connections: and save the workflow. Production runs use the new version once it is approved and activated.

secret_not_approved

What happened: “This version hasn’t been approved yet, so it can only read the secrets that the last approved version of this workflow reads. The secret X isn’t one of them. Use a dummy value for it in the workflow’s tests, or ask a person to approve this version.”

Why: a test run or dry run of a version that no person has approved gets a real value only for a secret that the workflow’s last approved version also reads. That way a draft can’t read a secret before anyone agreed it may. Here the version reads a secret that no approved version of this workflow reads, or the workflow has no approved version yet. Liitora gives the same answer whether or not the secret exists.

Like secret_not_declared, the whole run stops at this point, the script can’t catch it, and the attempt is recorded once in the audit log. Production runs and the workflow’s active or production version are not limited.

How to fix: give the secret a dummy value in the workflow’s tests (given.secrets) and check the workflow there. When it does what you want, ask a person to approve the version. After that its test runs and dry runs read the secret too. See Before a person approves the version.

production_secret_in_test

What happened: “The secret X belongs to a production connection, so a test run can’t use it.”

Why: a test run never gets production credentials. A script in a test run asked for a secret that a production connection uses.

The whole run stops at this point, and the script can’t catch it.

How to fix: give the test connection its own secret with test credentials, or use a dummy value for the secret in the workflow’s tests (given.secrets). See Test and production settings.

host_not_declared

What happened: “This version hasn’t been approved yet, so it can only reach the hosts of the connections it declares. The host X isn’t one of them. Add a connection for it to the workflow, or ask a person to approve this version.”

Why: a test run or dry run of a version that no person has approved sends web requests with a full URL (ctx.http.fetch, or http.request and webhook.send with a url) only to the hosts of the connections the version declares: their base URL and allowed hosts, with the same port. That includes the reads a dry run sends for real. Nothing was sent. Scripts see this as a host_error with this message.

How to fix: call the system through a connection, or declare a connection whose base URL or allowed hosts include this host. If the version is right as it is, ask a person to approve it.

email_not_approved

What happened: “This version hasn’t been approved yet, so it can’t send email. Start a dry run to see the email it would send, or ask a person to approve this version.”

Why: a version that no person has approved could send what it read to any address, so its test runs send no email. A dry run records the email it would have sent instead.

How to fix: start a dry run to check the email, or ask a person to approve the version.

timeout

What happened: a step, a script or a request took too long.

Why: each step attempt has timeout_minutes (default 15, at most 60), and scripts also have the plan’s run time limit. Requests time out after their connect or read time.

How to fix: make the step do less, or split it into several steps. For slow systems, use retry:.

network

What happened: a request failed before an answer arrived, for example because the connection broke.

Why: a short network problem. It is retryable.

How to fix: add a retry: policy with on: [network].

auth_failed

What happened: the connection could not get an access token.

Why: the OAuth 2 token endpoint refused the client id, the client secret or the refresh token. For an AWS connection, AWS refused the access key or the signature, or the role could not be assumed.

How to fix: check the client id and secret on the Secrets page and the token URL on the connection. For the authorization code method, select Reconnect on the connection. For AWS, the message says which: check the access key in the AWS connection’s secret, or check that the role’s trust policy names the IAM user and the connection’s external ID. See Connect AWS.

aws_clock_skew

What happened: AWS refused a request because of its time.

Why: every AWS request carries the time it was signed, and AWS refuses one that is too far from its own clock. The clock of the machine that signed the request is off. This is never a problem with your connection’s settings.

How to fix: on Liitora’s own workers, nothing: we are told and fix the time sync. On your own runner, check that the machine syncs its clock (NTP). The step is not retried, because a retry would carry the same wrong time.

connection_invalid

What happened: the connection’s settings cannot be used.

Why: for example the address is not https://, or a setting has the wrong form.

How to fix: open the connection on the Connections page and fix the setting the message names.

connection_not_bound

What happened: the step tried to use a connection slot that it did not bind.

Why: the step has no connections: entry for that slot.

How to fix: add the slot under the step’s connections:, for example connections: { api: internal-erp }.

connection_not_found

What happened: the connection the step names does not exist in this environment.

Why: test runs use the Test setup, production runs the Production setup. A test run never falls back to the production setup on its own.

How to fix: set up the connection for the environment on the Connections page. If the system has no test copy, see When a system has no test copy.

connection_kind_mismatch

Where: a finding under validation_failed (HTTP 422) when you save a workflow, or a step error in a run.

What happened: an action’s connection slot takes one kind of connection, for example visma, but the step binds it to a connection of another kind.

Why: an action written for one system cannot safely talk to another. The kind is checked when the workflow is saved and again before the step runs, in case the connection was replaced since then.

How to fix: bind the slot to a connection of the kind the action names (see the action’s Connection slots on the Library page), or create one.

rate_limited

What happened: too many requests. In a run: the connection’s request budget was used up. For a webhook sender: too many deliveries, or too many refused requests from the same address. When you invite people: too many invites were sent in a short time. For full exports: your company started 3 exports in the last 24 hours.

Why: a limit protects the other system and Liitora. Webhook endpoints accept 60 deliveries a minute by default, and your plan sets a company-wide limit. Separately, one sender address may have 60 requests a minute refused (for example with a wrong signature or an old URL). After that, its requests get this answer until the minute has passed, except correctly signed deliveries to an endpoint that is in use. The answer has a Retry-After header (HTTP 429 for webhooks).

The same goes for self-hosted runners and invite links: when 60 requests a minute from one network are refused (an unknown runner credential or registration token, or an invite link that does not exist), that network gets this answer for a while, even for a correct credential. The runner waits and tries again by itself.

Each admin can send 20 invites an hour, and your company 50 an hour in total. Sending an invite again to the same email counts too. The limit refills a little at a time, so you don’t have to wait the full hour. The message says how long to wait, and the API answers with HTTP 429 and a Retry-After header.

How to fix: for runs, add a retry: policy. For full exports, wait until 24 hours have passed since the oldest of them. For invites, wait the time the message says and send the invite again. For webhooks, have the sender slow down and retry after the number of seconds in Retry-After. If the sender also gets 401 answers, fix those first: see Webhook returns 401. For a runner, look for an old runner on the same network that still uses a revoked credential, and stop it or register it again.

secret_unavailable

What happened: the step could not read a secret.

Why: the secret is waiting for a value, has expired, or the secret store did not answer. The last case is retryable. In a test run it also happens when a test connection names a secret that belongs to a production connection.

How to fix: check the secret on the Secrets page. If it is set, retry the run.

signing_unavailable

What happened: webhook.send with sign: true could not sign the request.

Why: the connection bound to target names no signing secret (signing_secret).

How to fix: add a signing secret to the connection.

storage_unavailable

What happened: Liitora could not read or write the workflow’s state or files.

Why: a short outage on our side. It is retryable.

How to fix: retry the run.

infrastructure_error

What happened: a storage error interrupted the run.

Why: a short outage on our side.

How to fix: nothing. The run continues from its last finished step by itself.

worker_shutdown

What happened: the run was paused because Liitora was restarting.

Why: planned maintenance. The run goes back into the queue and does not use up an attempt.

How to fix: nothing. It continues by itself.

connection_waiting

What happened: the run paused because a connection it uses keeps failing. It shows in the run log, and the run waits in the queue.

Why: calls through the connection failed again and again (status 500 or higher, 429, or no answer), so Liitora stopped calling it for a while. Waiting does not use up an attempt. The step that was running starts again from the beginning when the run continues.

How to fix: nothing, usually. The run continues by itself once the connection works again. See A connection keeps failing.

connection_degraded

What happened: the run failed after waiting more than 24 hours for a connection that kept failing.

Why: runs don’t wait forever. As an alert, the same code tells your admins that a connection started failing.

How to fix: check the connection on Connections and fix it, then start the run again. See A connection keeps failing.

rate_budget_wait

What happened: the run paused because a connection it uses reached its shared request limit, or the other system asked Liitora to wait. It shows in the run log, and the run waits in the queue.

Why: calls over the limit wait their turn instead of failing. A wait longer than 30 seconds pauses the run instead of keeping the step busy. Waiting does not use up an attempt. The step that was running starts again from the beginning when the run continues.

How to fix: nothing, usually. The run continues by itself. See Runs wait for a request limit.

version_not_found

What happened: the workflow version of this run does not exist.

Why: this should not happen in normal use.

How to fix: report it with the run id.

invalid_definition

What happened: the stored workflow cannot be run.

Why: the definition cannot be read or planned. Saving checks this, so it is rare.

How to fix: save the workflow again as a new version, then report it with the run id.

invalid_condition

What happened: a step’s if: condition could not be evaluated.

Why: for example the expression divides by zero or calls a function with a wrong value.

How to fix: fix the expression. See expressions.

invalid_input

What happened: the step’s input is not valid for its action.

Why: a with: value has the wrong type or is missing after the expressions were evaluated, or an expression failed.

How to fix: read the message: it names the field and the rule (the value itself is hidden). Check the action’s inputs in the built-in actions.

invalid_output

What happened: the action returned something that does not match its output contract, or a script returned a value that is not JSON.

Why: a bug in the action or script.

How to fix: fix the action and publish a new version. For built-in actions, report it.

action_schema_invalid

What happened: the action’s input or output schema cannot be used.

Why: the action version was saved with a broken schema.

How to fix: publish a fixed version of the action.

action_failed

What happened: an action from your library or the platform library failed.

Why: its script threw an error or its checks failed.

How to fix: read the message and the step’s log lines.

action_not_found

What happened: the step’s action cannot be found.

Why: the owner or name in uses: is wrong, or no released version matches the pin.

How to fix: use your company’s name as the owner for your own actions and library for the platform library. See action references.

action_not_pinned

What happened: “This step’s action was not found when the workflow was saved, so no version of it is approved to run. Save the workflow again to make a new version.”

Why: when you save a workflow, Liitora records the exact version of each action it uses, and runs only that version. This action didn’t exist yet when the workflow was saved, so no version was recorded.

How to fix: save the workflow again (no change is needed). Production runs use the new version once it is approved and activated. See How Liitora picks a version.

workflow_not_found

What happened: the workflow called with uses: workflow/... is not one of your workflows.

Why: the owner must be your company’s name.

How to fix: fix the reference.

builtin_not_available

What happened: the built-in action is not available.

Why: the name or major version in uses: platform/... does not exist.

How to fix: check the name in the built-in actions.

invalid_uses

What happened: the uses: value cannot be read.

Why: it does not have one of the allowed forms.

How to fix: see action references.

step_invalid

What happened: the step has neither uses: nor run:.

How to fix: give the step one of them.

script_invalid

What happened: a script does not pass the safety checks.

Why: for example it imports a module, uses eval, or reads a secret with a name that is not a plain text.

How to fix: read the first finding in the message and fix the script.

invalid_for_each

What happened: strategy.for_each did not give a list.

Why: the expression failed or returned something else than a list.

How to fix: make for_each return a list, for example ${{ steps.fetch.outputs.json.items }}.

for_each_failed

What happened: some items of a for-each step failed. The message says how many, for example “2 of 10 items failed”.

Why: see the errors of the failed items in the run view.

How to fix: fix the cause and use Retry from this step. Items that succeeded are not run again.

items_quarantined

What happened: the run finished, but some items of a for-each step kept failing and were set aside (quarantined). The message says how many, for example “2 of 50 items of step update were quarantined”, and gives the first error.

Why: the step has strategy.quarantine: true. Each of these items still failed after its retries, so the run processed the other items and the later steps, and then ended as failed so that somebody looks.

How to fix: open the run and look at Quarantined items. Fix the cause (the data in the other system, a missing permission, a limit), then replay the items one by one or all at once. See Replay quarantined items. A replay that fails again also ends with this code, and the item waits on the original run again.

item_changed

What happened: a replay did not run an item, because the item is no longer the same as when it was quarantined.

Why: a replay builds the item again from the original run’s results. Liitora keeps a fingerprint of each quarantined item, not the item itself, and the fingerprint did not match.

How to fix: start a new run of the workflow to process the current data.

replay_incomplete

What happened: a replay run ended without running the step of the quarantined items.

Why: the step did not run in the replay, for example because its if: condition was false this time.

How to fix: check the step’s condition, then replay the items again from the original run. They are still waiting there.

output_too_large

What happened: a step’s output is larger than your plan allows.

Why: outputs are kept for later steps and have a size limit.

How to fix: write large data to a file (artifact) instead, and pass only what later steps need.

artifact_exists

What happened: the step tried to make a file with a name the run already has, or a name that is another file’s name plus a dot and more (report and report.id, in either order).

Why: in an expression, artifacts.report.id must always mean the same file.

How to fix: give each file in a run its own name that does not start with another file’s name and a dot.

artifact_not_found

What happened: the step asked for a file this run does not have.

How to fix: check the name. A run can only read its own files.

call_refused

What happened: the called workflow could not be started.

Why: the message says why, for example a limit.

How to fix: read the message.

called_workflow_failed

What happened: the workflow this step called ended without success.

How to fix: open the called run from the step and fix it there.

called_workflow_missing

What happened: the run this step started no longer exists.

How to fix: retry from this step.

call_not_stubbed

Where: workflow tests only.

What happened: a test reached a step that calls another workflow.

Why: tests never start other workflows.

How to fix: stub the step in the test with given.stub_steps and the outputs the called workflow returns. See the test case format.

http_unmocked

Where: workflow and action tests only.

What happened: a test made an HTTP request that no mock answers.

Why: tests never reach the network.

How to fix: add a mock under given.http for that request.

template_not_found

What happened: email.send or pdf.render could not find its template.

Why: no template with that name is stored in Settings > Templates, or it was removed.

How to fix: check the name in template:, or add the template. See Use email and PDF templates.

Script errors

A step with run: or a transform script ends with one of these codes when the script fails.

syntax_error

What happened: the script cannot be parsed, or it uses import.

How to fix: fix the line and column in the message. Scripts cannot import modules: use actions to reuse code between steps.

script_error

What happened: the script threw an error that it did not catch.

How to fix: the message has the error and the script line. Fix the script or catch the error.

host_error

What happened: a call to ctx failed and the script did not catch it, for example a blocked address or a missing connection slot.

Why: the error’s own code tells more: invalid_argument, denied, not_found, timeout, limit_exceeded, failed or rejected.

How to fix: read the message. See the host API.

no_default_export

What happened: the script has no export default function.

How to fix: write the script as export default async function run(ctx, input) { ... }.

unresolved_promise

What happened: the script waited for something that can never finish.

How to fix: make sure every await waits for a ctx call or a promise that settles.

cpu_limit

What happened: the script used more CPU time than allowed.

How to fix: make the script do less work per step, for example process fewer items.

memory_limit

What happened: the script used more memory than your plan allows.

How to fix: handle less data at a time.

stack_overflow

What happened: the script called itself too deeply. A script cannot catch this.

How to fix: replace deep recursion with a loop.

format_error

What happened: the script gave ctx.formats data it could not read or write, and did not catch the error. A built-in action such as xml.parse got data it could not read, or a webhook body could not be read as the trigger’s parse format. For example, the XML is not well-formed, a CSV row has the wrong number of fields, an NDJSON line is blank, text is not valid in the encoding it claims, an Excel file has macros or is not an .xlsx workbook, a fixed-width value is too long for its field, a zip file is damaged or would unpack to too much, a form has a broken % code, or the data is too large or nested too deeply.

Why: Liitora refuses data that could be read in more than one way or that could attack the reader. The same data fails the same way every time, so the step is not retried.

How to fix: read the message, which names the problem and usually the line. Fix the data where it comes from, or catch the error in the script (err.code is FORMAT_ERROR) and handle it. See XML in scripts, CSV in scripts, Excel and fixed-width files in scripts, Forms and file uploads in scripts, Text encodings and binary data and Data formats.

Too large to start: a script that is too large to start fails with invalid_request (the script can be at most 1 MiB, its input and event at most 4 MiB).

codec_unavailable

What happened: a built-in action such as xml.parse or csv.parse could not start the sandbox that reads the data. Liitora reads data from outside only inside the sandbox, never in the worker itself, so the step stopped instead.

Why: a temporary problem on our side, for example the system was very busy. Your data was not read and nothing was changed.

How to fix: run the workflow again. A step whose retry includes network tries again on its own. If it keeps happening, contact support. See Data formats.

AI errors

These come from ai.generate steps. See Connect an AI model.

ai_invalid_output

What happened: the model’s answer was not used, because it was not JSON or did not match output_schema.

Why: Liitora uses only answers that fit the schema, so later steps never get a made-up field.

How to fix: make the prompt say clearly what to answer, and check that the schema allows every answer you expect. A smaller schema with an enum is easier for a model to follow.

ai_refused

What happened: the model refused to answer.

Why: the provider’s model decided not to answer this prompt or input.

How to fix: check that the prompt and the input are what the task needs. Send less data if you can.

ai_truncated

What happened: the answer was cut off at max_output_tokens, so it was not used.

Why: the answer needed more tokens than the step allows.

How to fix: raise max_output_tokens, or ask for a shorter answer.

ai_content_filter

What happened: the provider’s content filter removed the answer.

Why: the provider’s own safety settings blocked the prompt, the input or the answer.

How to fix: check the input. On Azure OpenAI, check the content filter of your deployment.

ai_token_limit

What happened: the run reached its AI token limit, so no more AI calls are made in this run.

Why: each run may use a set number of AI tokens (ai_tokens_per_run). Liitora checks before each call and counts after it.

How to fix: send less data, lower max_output_tokens, or split the work over more runs. To raise the limit, contact us.

ai_connection_required

What happened: the step’s model slot is not bound to an AI connection.

Why: ai.generate only calls a model through a connection made from an AI template.

How to fix: add an AI connection and bind it to model.

ai_auth

What happened: the provider did not accept the API key.

How to fix: check the secret the connection uses, or create a new key and update the secret. Then select Test connection.

ai_forbidden

What happened: the API key may not use this model or this region.

How to fix: check the key’s project and permissions with the provider. For OpenAI’s EU region, check that the project is approved for EU data residency.

ai_quota

What happened: your account with the provider has no credit or quota left, or reached its spending limit.

How to fix: check billing and limits with the provider. The step is not tried again.

ai_bad_request

What happened: the provider refused the request, for example because the model name is wrong or it can’t use your schema.

How to fix: read the message, check model (on Azure, the deployment name) and the schema. Some providers support only part of JSON Schema.

ai_rate_limited

What happened: the provider limited how fast you can call it.

How to fix: the step already tried again. Run fewer AI steps at the same time, or ask the provider for a higher limit.

ai_unavailable

What happened: the provider was busy or had an error.

How to fix: the step already tried again when the provider allows it. Add a retry: policy to try later.

ai_provider_error

What happened: the provider reported an error while answering, or answered in a way Liitora doesn’t expect.

How to fix: try again later. If it keeps happening, check the provider’s status page.

Email errors

email.send steps fail with these codes. Only email_unavailable is retried.

email_not_configured

What happened: there is no email sender to send from.

How to fix: add an email sender. See Set up email senders.

email_sender_unverified

What happened: your email sender is not verified.

Why: a sender is verified by a successful test email. After any change it needs a new test. Liitora never falls back to another domain.

How to fix: send a test email from the sender, then run the workflow again.

email_sender_not_allowed

What happened: the from address is not one the sender may send as.

How to fix: use one of the sender’s addresses, or add the address to the sender.

email_invalid

What happened: the message is not valid: for example a bad address, more than 100 recipients, a subject with a line break, or attachments over 20 MB.

How to fix: read the message and fix the step’s input.

email_sender_reconnect

What happened: the mail server or Microsoft 365 refused the sign-in.

How to fix: update the sender’s password or client secret on the Secrets page, then send a test email.

email_rejected

What happened: the mail server refused the message.

How to fix: check the recipients and the sender’s DNS records (SPF, DKIM and DMARC).

email_unavailable

What happened: the mail server did not answer or asked to try later.

How to fix: nothing. The step is retried when it has a retry: policy. Otherwise retry the run.

email_sender_misconfigured

What happened: the sender’s settings cannot be used.

How to fix: check the host, port and security setting of the sender. If the message says “This address points to a private network, which Liitora can’t reach.”, the server is on a private network or its name only exists inside one. Use the mail server’s public host name. See Private address blocked.

Webhook delivery responses

The system that calls your webhook URL gets these answers. Accepted deliveries get 202 with {"event_id", "run_ids", "duplicate": false}. A repeated delivery with the same idempotency key gets 200 with the first delivery’s ids and "duplicate": true, and starts nothing new. The codes unauthorized (401), invalid_request (400), payload_too_large (413), unsupported_media_type (415) and rate_limited (429) are described above. For a webhook, invalid_request means Liitora could not record the delivery as it was sent, for example because a header is too long; sending it again unchanged fails again. See also Webhook signing.

account_restricted

HTTP status: 403.

What happened: the company cannot accept webhooks right now.

Why: the company is suspended or its billing is restricted.

How to fix: an admin checks the billing status.

invalid_body

HTTP status: 400.

What happened: the body could not be read as its content type says, for example broken JSON.

Why: the body doesn’t match its Content-Type, the JSON is nested more than 64 levels deep or has a number too large to store (such as 1e400), or the body contains a NUL character (a JSON \u0000, or a zero byte in text, XML or a form). Liitora can’t store NUL characters, so it refuses them instead of asking the sender to retry. A %00 in a form is accepted here, and the run then fails with format_error.

How to fix: send a body that matches the Content-Type header, without NUL characters.

request_timeout

HTTP status: 408.

What happened: the body of the delivery did not arrive in time.

Why: the whole body must arrive within 10 seconds of the request. Liitora drops requests that send their body very slowly, so they can’t hold the connection.

How to fix: send the whole body at once. If the sender is behind a slow link, send smaller bodies, for example only ids.

invalid_idempotency_key

HTTP status: 400.

What happened: the Idempotency-Key header is not valid.

How to fix: send it once, with 1 to 255 visible ASCII characters.

idempotency_key_reused

HTTP status: 422.

What happened: this Idempotency-Key was already used for a delivery with a different body. A repeat with the same key must have the same body, so Liitora didn’t record this one and started nothing. Your company’s audit log shows it as webhook.idempotency_key_reused.

How to fix: give every event its own key, for example the order id plus what happened (order-1234-created). When you retry a delivery, send exactly the same body with the same key.

unavailable

HTTP status: 503, with Retry-After: 5.

What happened: the delivery could not be recorded right now.

How to fix: the sender retries later. Most senders do this by themselves.

Runner errors

These codes come from runners in your own environment and the runner groups they belong to.

runner_group_missing

HTTP status: 409.

What happened: you saved, approved or activated a workflow with runs-on: self-hosted/<group>, but your company has no runner group with that name.

Why: a workflow that names a group runs only on that group’s runners. Without the group, no runner would ever run it. An approval also records what the group sends back, so the group must exist when someone approves or activates the workflow.

How to fix: ask a company admin to add the group under Settings, Runners, then approve or activate again. Or remove runs-on to run the workflow on Liitora. See Run automations in your own environment.

runner_limit_reached

HTTP status: 409.

What happened: a new registration token for a runner was refused.

Why: your plan doesn’t include runners, or all the runners your plan allows are in use. Unused registration tokens count too, until they run out after one hour.

How to fix: remove a runner you no longer need, or wait until an unused token runs out. For more runners, ask the account owner about a larger plan. See Limits per plan.

runner_unsupported

What happened: a step of a workflow that runs on your own runner failed before it did anything.

Why: it uses something that isn’t available on runners yet: calling another workflow, saving files from a run, setting items aside, certificate sign-in, or retrying from a chosen step. Change detection with snapshot: true (platform/sync.diff) also gives this code when the runner group sends back only statuses and timings, because a snapshot keeps the record keys on Liitora.

How to fix: change the step so it doesn’t need that feature, or remove runs-on to run the workflow on Liitora. For change detection, compare with a target list, or use a runner group that sends everything back. See Run automations in your own environment.

runner_resume_unavailable

What happened: a run on your own runner stopped, because the output of an earlier step was no longer there.

Why: when a runner group sends back only statuses and timings, step outputs stay on the runner that made them. If the run moved to another runner, or the runner restarted or ran out of room for outputs, a later step can’t read them.

How to fix: start the run again. If it happens often, give the runner more memory or fewer runs at the same time (LIITORA_RUNNER_CONCURRENCY).

runner_released

What happened: the runner handed the run back before it finished, for example because it was stopped.

Why: a runner that shuts down returns the runs it is working on.

How to fix: nothing in most cases. The run can be tried again by another runner of the group. If no runner is left, start one. See Run automations in your own environment.

runner_claim_failed

What happened: a runner took a run but couldn’t prepare it.

Why: a passing problem, for example a short database outage. The run goes back to the queue.

How to fix: nothing. The run is tried again. If it keeps happening, contact support.

return_mode_not_approved

What happened: a run of a workflow on your own runner failed before it started, and nothing was sent to the runner. Activating the workflow can be refused with the same code.

Why: the runner group now sends back more than the version was approved with. This happens when someone removed the group and added it again with Everything, like a run on Liitora (full), while the version was approved when the group sent back Only statuses and timings (metadata). Liitora doesn’t let a group send back more data than the approver saw. It also happens when nobody approved or activated the version for its group, for example a version activated before this check existed.

How to fix: if the group should send back everything, save the workflow again (no change is needed), then approve and activate the new version. If it should send back only statuses and timings, remove the group and add it again with that setting, then start the run again. See Where your data goes.

lease_lost

What happened: a runner reported on a run it no longer holds.

Why: the runner didn’t report for about two minutes, so the run went back to the queue, or the run already ended. The runner stops working on it and takes the next one.

How to fix: nothing for this run. If it happens often, check that the runner’s machine has enough CPU and a steady connection to Liitora.

webhook_event_unavailable

What happened: a run started by a webhook that your runner received failed before it started, because the runner no longer has the delivery.

Why: with receive: runner, only the runner that received a delivery keeps it. The run fails when the runner removed the delivery after its retention period (14 days unless you set another), lost its webhook folder, or was removed, or when its runner group was removed, while the run was still waiting.

How to fix: ask the sender to send the delivery again. If runs wait long enough for this to happen, check that the runner is running. See Receive webhooks inside your network.

policy_refused

What happened: a run of a workflow on your own runner failed before it started, because the runner’s local policy doesn’t allow this version of the workflow. Nothing in the workflow ran.

Why: the runner’s operator limits what the runner may run with a policy file, and this version goes beyond it. The run view says which rule it hit and, where there is one, the item:

• Destination not listed: the version reaches a host that the policy’s destinations don’t list.
• Secret name not allowed: the version uses a secret whose name doesn’t start with any of the policy’s secret_prefixes.
• Secret name not approved yet: the policy asks for each secret name to be approved, and this one isn’t in approved_secrets.
• Action or version not allowed: the version uses an action, or a version of an action, that the policy’s actions don’t allow.
• Scripts not allowed: the version has code of its own (a run: step or platform/transform), and the policy says scripts: deny.

Liitora never sees the policy itself, only the rule and the item.

How to fix: ask the runner’s operator to change the policy and restart the runner, or change the workflow so it stays within the policy. Then start the run again. See Limit what your runner may run.

runner_store_refused

What happened: Liitora refused a change a runner tried to make for a run, so the runner stopped that attempt.

Why: the change doesn’t fit the run, for example it is too large or names something the run doesn’t have. Liitora tries the run again or fails it.

How to fix: open the run to see how it ended. If a step’s data is too large, make it smaller. If it keeps happening, contact support.

Alerts

These kinds of alerts become incidents and reach your admins by email, or the channels you set up. See Set up alerts.

connection_degraded (alert)

What happened: a connection kept failing, so runs that use it now wait instead of calling it. You get one alert per outage, not one per run.

How to fix: see A connection keeps failing.

library_item_flagged (alert)

What happened: Liitora flagged a version of a library workflow, and your company has workflows copied from exactly that version. The alert names the version, Liitora’s reason and up to five of the workflows. Your admins are always emailed for it, even when alert rules exist. You get one alert per flagged version.

How to fix: open Workflow library and select Pause the running copies on the notice. See If Liitora flags a version you use.

runner_unavailable (alert)

What happened: runs of one of your runner groups waited more than 10 minutes, and no runner of the group contacted Liitora in that time. These runs never move to Liitora’s own workers. You get one alert per outage, not one per run.

How to fix: start a runner of the group, or check that it can reach Liitora. See Run automations in your own environment.

quota_exceeded

What happened: your company reached its monthly run limit, so no new production runs start this month. A webhook sender gets this code with 429 and Retry-After.

How to fix: see Quota exceeded.

quota_warning

What happened: your company used 80% or 100% of its monthly soft run limit.

How to fix: check which workflows run most on the usage data. See Understand usage and limits.

trigger_misfire

What happened: scheduled runs were missed, for example during an outage, or a schedule could not be read. The alert says how many and when.

Why: missed slots older than 5 minutes are skipped, not run late.

How to fix: start a run by hand if you need the missed one.

freshness_violation

What happened: a workflow did not succeed by the time its expect: says.

How to fix: open the workflow’s runs to see why. See Set freshness expectations.

run_refused

What happened: a scheduled run was not started because the company is suspended or its billing is restricted.

How to fix: an admin checks the billing status.

schedule_too_frequent

What happened: a schedule runs more often than your plan allows. When you save, this is a validation finding. After a plan change, the scheduler skips the runs and sends this alert.

How to fix: make the schedule less frequent, or change the plan. See Limits per plan.

Validation findings

These codes appear as findings under validation_failed when a workflow is saved or validated. Each finding carries its own “what went wrong” and “how to fix” text and the line and column in the YAML, so they are listed here only by topic. Warnings (no_triggers, shift_without_skip_on, deprecated_action, unknown_lookup_table, ai_output_to_write_target unless strict mode is on, and hardcoded credentials written by a person) do not block a save.

Topic	Codes
The YAML file	yaml_syntax, yaml_empty, yaml_multiple_documents, yaml_duplicate_key, yaml_too_large, yaml_too_deep, yaml_unsupported, not_a_mapping, unknown_key, missing_key, invalid_value
Name and description	missing_name, missing_description, name_not_plain_language, text_too_long, invalid_text
Triggers	no_triggers, too_many_schedules, invalid_cron, invalid_timezone, schedule_too_frequent, unknown_calendar, duplicate_calendar, unknown_shift, unknown_misfire, shift_without_skip_on, invalid_webhook_endpoint, unknown_webhook_parse, unknown_webhook_receiver, webhook_receiver_needs_runner, invalid_workflow_run, invalid_time_of_day, invalid_expect_days, empty_concurrency_group
Steps	no_steps, too_many_steps, missing_id, invalid_id, duplicate_id, both_uses_and_run, empty_run, run_too_large, script_expression, html_expression, invalid_action_ref, missing_action, wait_without_workflow, invalid_timeout, invalid_retry_attempts, invalid_retry_on, empty_retry_on, invalid_max_parallel, for_each_not_a_list
Order of steps	unknown_need, self_need, duplicate_need, dependency_cycle, chain_too_deep, workflow_call_cycle, workflow_call_too_deep
Inputs and connections	unknown_input, missing_input, invalid_input, input_type_mismatch, unknown_output, missing_connection, invalid_connection_name, invalid_connection_slot, unknown_connection_slot, connection_slot_not_bound, connection_slot_not_declared, action_connection_not_declared
Expressions	invalid_expression, unknown_name, unknown_function, wrong_argument_count, status_function_outside_if, root_not_allowed, unknown_step_reference, unknown_step_property, step_not_upstream, self_reference, not_a_need, each_outside_for_each, unknown_each_property, evaluation_error
Library and tests	unknown_action, unknown_workflow, unknown_connection, unknown_lookup_table, deprecated_action, action_source_invalid, invalid_tests, tests_too_large, invalid_schema, invalid_semver, invalid_connection_slots, major_version_required, schema_too_large, schema_too_deep, schema_too_complex, schema_recursive_ref, schema_unsupported_ref, connection_kind_mismatch
Scripts	the script checks, for example import_forbidden, forbidden_eval, forbidden_global, secret_name_not_literal, connection_slot_not_literal, ctx_indirect_use, ctx_shadowed, arguments_forbidden, missing_default_export
AI	ai_output_to_write_target: an AI answer reaches a recipient, an address, a file path or another write target. A warning that the approver confirms, or an error when your company has strict mode on
Credentials	credential_private_key, credential_jwt, credential_api_key, credential_stripe_key, credential_github_token, credential_liitora_token, credential_aws_key, credential_slack_token, credential_slack_webhook, credential_google_api_key, credential_azure_key, credential_url_userinfo, credential_bearer_token, credential_basic_auth, credential_query_parameter, credential_named_value, credential_high_entropy

A credential finding means a value looks like a real password, key or token. Move it to a secret and read it with ctx.secrets.get("name"), or use a connection. In test fixtures, use an obvious dummy such as "<test-dummy>", and put dummy secret values under given.secrets. For AI assistants every credential finding is an error. For people it is a warning.

Next steps

• Common failures and how to fix them
• Read run logs
• MCP tools