> ## Documentation Index > Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt > Use this file to discover all available pages before exploring further. # Errors and exit codes > The typed error line, every exit code, the --json error envelope, debug output, and the common CLI errors with their fixes 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`](/reference/cli/logs). *Verified against lua-cli 3.33.0.* ## Error format The line is `✖ : `. A `💡` hint follows when the CLI knows the remedy, and a server validation refusal adds one indented `•` line per issue between the two. ```bash theme={null} lua test bogus --ci # "bogus" is not a type ``` ```text Output theme={null} ✖ 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: ```text Output theme={null} ✖ 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 --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 `. | | `7` | `lua workflows` run | `--timeout` elapsed while the run was still live. | The run continues; `lua workflows watch ` 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_`, except on `lua workflows`, where every 4xx other than 404 exits 1). | Use a credential with access to the agent; for `http_`, 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 "" not found.`, `Persona version not found.`, `Version v not found`, `Agent version v not found.` | | `lua env -k ` | The variable does not exist | `1`: `✖ error: Variable "" not found` | | `lua workflows` | Any 4xx other than 404, including a 424 provider refusal | `1`: `✖ error: failed (): ` | | `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 `⚠️ 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 "" needs --approve/--deny (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: ```json theme={null} { "success": false, "error": { "code": "", "statusCode": 404, "message": "", "issues": [{ "path": "", "message": "", "code": "" }] } } ``` `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 --force` | | `✖ usage: Project already initialized with agent ` | Non-interactive `lua init` in a bound project | Add `--force`, or use an empty directory | | `✖ usage: lua: "" is not a valid 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 `, `lua push skill --name ` | | `✖ 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 ` 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 --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 "" not found` | `lua test skill --name` got a skill name or a misspelt tool | Pass the tool's `name` field | | `✖ error: "" is not pushed: ` | The server refused the version; `•` lines say why | Fix the issue; for `already exists`, `lua push --force` auto-bumps | | `✖ not_found: "" () 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 push: …` | The primitive pushed but the source backup did not | `lua push backup --force --fresh`; do not re-push | | `✖ error: No versions found for "". Push it first using: lua push ` | Deploying before any push | `lua push ` | | `✖ error: Version "" 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 "" reads env keys with no value in the target env: …` | `env()` keys unset in that environment | `lua env production -k -v `; `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 ` | ## Still stuck Send `support@heylua.ai` 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](/ship/troubleshooting). ## See also * [CLI overview](/reference/cli/overview) — global flags and credential precedence * [`lua logs`](/reference/cli/logs) — runtime failures of deployed code * [Automate releases in CI](/ship/ci-and-automation) — branching on exit codes