Errors and exit codes

Every lua command that fails prints one typed line on stderr and exits with a code that names the class of failure. Start with lua status --json for the environment, credential source, project, and sync state; rerun the failing command with LUA_DEBUG=1 to print the stack trace; read runtime failures of deployed code with lua logs. Verified against lua-cli 3.33.0.

Error format

The line is ✖ <class>: <message>. A 💡 hint follows when the CLI knows the remedy, and a server validation refusal adds one indented • line per issue between the two.

lua test bogus --ci   # "bogus" is not a type

Output

✖ usage: lua: "bogus" is not a valid test.type value.
💡 Valid values: job, postprocessor, preprocessor, skill, webhook, workflow

Errors the option parser catches before the command runs, such as an unknown flag or a missing argument, print the parser’s own line instead, for example error: unknown option '--bogus', and exit 2. With LUA_DEBUG=1, or --debug anywhere on the line, the stack trace follows after a blank line:

Output

✖ usage: Type must be specified when using the --name option.
💡 Usage:
     lua test skill --name mySkill --input "{...}"      Test skill with JSON input
     lua test webhook --name myWebhook --input "{...}"  Test webhook with JSON input

CliError: Type must be specified when using the --name option.
…

LUA_NO_HINTS=1 silences the ✨ Tip: lines after a successful command and the 💡 Diagnose: follow-ups under an error. The hint that explains the error itself is always printed.

Exit codes

Code	Class	Meaning	What to do
`0`	ok	Success. Also a declined confirmation prompt, and a `lua test` run whose tool threw.	Read the output: `lua test` reports a thrown tool as `status: 'error'`; bare `lua push` lists failed components.
`1`	`error`	Unclassified failure; the message says what. A compile failure is `compile_failed`. Some commands report a missing version or variable, drift, or a 4xx here instead of `2`, `3`, or `10`; see the known exceptions below.	Fix what the message names; `LUA_DEBUG=1` prints the stack. Retrying unchanged fails again.
`2`	`usage`	Bad arguments, unknown type or action, invalid JSON input, no project or agent configured (except `lua deploy`, which exits 1); `lua test workflow` also uses it for an unanswered approval, signal, or resume.	Fix the command line; the `💡` hint lists the valid values or flags.
`3`	`not_found`	The named tool, primitive, agent, organization, or user session does not exist (HTTP 404). A missing version exits 1 on `lua deploy`, `lua version`, and `lua chat --agent-version`.	Check the name or id with the matching `view` or `list` command.
`4`	`lua workflows` run	The run ended `failed` or `timed_out`; `lua test workflow` also uses it for a replay divergence.	`lua workflows status <run-id> --steps` names the failed step.
`5`	`lua workflows` run	The run ended `cancelled` or `abandoned`; `lua test workflow` uses it for a missing fixture.	Start a new run, or record the fixture.
`6`	`lua workflows` run	The run is gated awaiting consent.	Approve it from the desktop, then `lua workflows watch <run-id>`.
`7`	`lua workflows` run	`--timeout` elapsed while the run was still live.	The run continues; `lua workflows watch <run-id>` resumes following it.
`8`	`lua workflows` run	The run is parked waiting for a person (approval, input, signal, billing).	Run the verb the command printed, or pass `--wait-for-human`.
`9`	`auth`	No credential, or the platform refused it (HTTP 401).	`lua auth configure`, or set `LUA_API_KEY`. Do not retry unchanged.
`10`	`forbidden`	The credential is valid but may not do this (HTTP 403; any other 4xx is reported as `http_<status>`, except on `lua workflows`, where every 4xx other than 404 exits 1).	Use a credential with access to the agent; for `http_<status>`, fix the request.
`11`	`unavailable`	The platform or the network failed (HTTP 5xx, connection refused, timeout).	Retry after a pause; check the network and `https://status.heylua.ai`.
`12`	`provider_rejected`	The model provider refused the request (HTTP 424); retrying unchanged fails identically. `lua workflows` reports a 424 with exit 1 and the same hint.	Fix the provider key or model code named in the hint.

Codes 4–8 are run outcomes and exist only on lua workflows and lua test workflow; every other command skips them, so a script never mistakes an expired key (9) for a canceled run (5). lua --help prints the same table.

Known exceptions

These commands depart from the table; a script that branches on the exit code needs the message as well.

Command	Case	Exit code and message
`lua deploy`, `lua version show`, `lua version promote`, `lua chat --agent-version`	The version does not exist	`1`: `✖ error: Version "<ver>" not found.`, `Persona version <n> not found.`, `Version v<n> not found`, `Agent version v<n> not found.`
`lua env <environment> -k <KEY>`	The variable does not exist	`1`: `✖ error: Variable "<KEY>" not found`
`lua workflows`	Any 4xx other than 404, including a 424 provider refusal	`1`: `✖ error: <verb> failed (<CODE>): <message>`
`lua deploy`	Not inside a project	`1`: `✖ error: No lua.skill.yaml found. Please run this command from a skill directory.`
`lua status`, `lua compile --sync`	No credential	`0`: `status` reports `auth.authenticated: false`; `compile --sync` skips the drift check without a message
`lua deploy all --force`	Some items failed to deploy	`0`, with `⚠️ <n> deployment(s) failed:` and `Re-deploy failed items with: lua deploy all --force`
`lua sync --check`	Drift found	`1`: the drift summary, then `✖ error: Operation failed`
`lua test workflow`	An approval, signal, or resume has no flag answer and no terminal (stdin is not a TTY, or `--json`)	`2`: `✖ usage: approval "<stepId>" needs --approve/--deny <stepId> (no interactive stdin)` (`APPROVAL_UNANSWERED`; also `SIGNAL_UNANSWERED`, `RESUME_UNANSWERED`)

JSON error envelope

The commands that accept --json and opt into the envelope (lua workflows, lua auth sessions, lua marketplace) print a failure on stdout as JSON instead of the typed line, so a script parses one shape whether the call succeeded or not:

{
  "success": false,
  "error": {
    "code": "<server code, or the CLI class such as not_found>",
    "statusCode": 404,
    "message": "<message>",
    "issues": [{ "path": "<field>", "message": "<why>", "code": "<rule>" }]
  }
}

code is the server’s discriminator when it sent one, otherwise the CLI class. statusCode and issues appear only when known. Other commands, including lua test --json, keep the typed line on stderr. The stack trace still goes to stderr when debug is on.

Common errors

Project and usage

Message	Cause	Fix
`✖ usage: No lua.skill.yaml found — run this command from a Lua project directory.` (`lua deploy` exits 1 with `✖ error: No lua.skill.yaml found. Please run this command from a skill directory.`; `lua git` uses that text as `usage`)	Not in a project	`cd` into the project, or run `lua init`
`✖ usage: Missing agentId in lua.skill.yaml.`	The `agent:` block is empty	`lua init --agent-id <id> --force`
`✖ usage: Project already initialized with agent <id>`	Non-interactive `lua init` in a bound project	Add `--force`, or use an empty directory
`✖ usage: lua: "<value>" is not a valid <group> value.`	Unknown type or action	Use a value from the hint
`Type must be specified when using the --name option.` (`lua test`: `✖ usage:`, exit 2; `lua push`: `✖ error:`, exit 1)	`--name` without a type	Put the type first: `lua test skill --name <tool>`, `lua push skill --name <skill>`
`✖ error: Interactive prompt required but --ci flag is set. Provide all required flags or arguments.`	A prompt was reached under `--ci`	Pass the type, `--name`, `--set-version`, or `--force`
`✖ usage: Invalid JSON input: …`	`--input` is not valid JSON	Quote the JSON for your shell; workflows accept `@file`
`✖ error: The "all" type requires the --force flag`	`push all` or `deploy all` without `--force`	Add `--force`

Authentication

Message	Cause	Fix
✖ auth: No Lua CLI authentication found. Run `lua auth configure` or set LUA_API_KEY.	No credential in any source	`lua auth configure`, or export `LUA_API_KEY`
`✖ auth: Your Lua CLI session was signed out.`	The user session was ended elsewhere: `lua auth logout --all`, a revoke, or a dashboard sign-out	`lua auth configure`
`✖ auth: …` with hint `Re-authenticate or check your API key`	The platform answered 401	`lua auth configure --api-key <key>` with a valid key
`✖ auth: …` with hint `Your API key is valid, but it does not have access to the agentId in lua.skill.yaml`	The project points at an agent this credential cannot see	`lua agents`, then `lua init --agent-id <id> --force`
`✖ forbidden: Scoped CLI credentials cannot create a new agent.` or `… cannot duplicate an agent.`	`lua init --agent-name` or `--from-agent-id` with a scoped key	Sign in with email, or create the agent in the admin dashboard and pass `--agent-id`

Compile, test, push, and deploy

Message	Cause	Fix
`✖ compile_failed: Compilation failed — see errors above.`	A validation or bundling error, listed with file and line	Fix the listed file; `lua compile --verbose` for context
`✖ not_found: Tool "<name>" not found`	`lua test skill --name` got a skill name or a misspelt tool	Pass the tool’s `name` field
`✖ error: <type> "<name>" is not pushed: <reason>`	The server refused the version; `•` lines say why	Fix the issue; for `already exists`, `lua push <type> --force` auto-bumps
`✖ not_found: <Type> "<name>" (<id>) no longer exists on the server`	`lua.skill.yaml` holds an id deleted server-side	Remove that id line and push again
`Source backup failed after <type> push: …`	The primitive pushed but the source backup did not	`lua push backup --force --fresh`; do not re-push
`✖ error: No versions found for <Type> "<name>". Push it first using: lua push <type>`	Deploying before any push	`lua push <type>`
`✖ error: Version "<ver>" not found.` (exit 1, not 3)	`--set-version` names a version that was never pushed	Use a listed version or `latest`
`env-key-missing: workflow "<name>" reads env keys with no value in the target env: …`	`env()` keys unset in that environment	`lua env production -k <KEY> -v <value>`; `LUA_PUSH_ENV_CHECK=error` makes it fatal

Network and provider

Message	Cause	Fix
`✖ unavailable: fetch failed`	No route to the API	Check the network and `https://status.heylua.ai`, then retry
Hint containing `503 UPSTREAM_UNAVAILABLE` or `503 VENDOR_UNAVAILABLE`	The API is up; a Lua service or a third party behind it is not	Retry when the hint says so; quote the request id if it persists
`✖ provider_rejected: Your model provider rejected the request (401 invalid_api_key): …`	The organization’s own provider key is wrong	Fix the key in the agent’s model settings in the admin dashboard
`✖ provider_rejected: … (404 model_not_found): …`	The provider does not serve the configured model	`lua models set --model <code>`

Still stuck

Send [email protected] the command you ran, the full stderr output including the ✖ line, and the output of lua status --json --ci, which reports LUA_API_KEY only as set or not set. For failures inside deployed code that do not surface as CLI errors, see Troubleshooting.

SDK

CLI

REST API

Errors and exit codes

Error format

Exit codes

Known exceptions

JSON error envelope

Common errors

Project and usage

Authentication

Compile, test, push, and deploy

Network and provider

Still stuck

See also

​Error format

​Exit codes

​Known exceptions

​JSON error envelope

​Common errors

​Project and usage

​Authentication

​Compile, test, push, and deploy

​Network and provider

​Still stuck

​See also

Error format

Exit codes

Known exceptions

JSON error envelope

Common errors

Project and usage

Authentication

Compile, test, push, and deploy

Network and provider

Still stuck

See also