✖ <code>: <message>, followed by a 💡 hint when there is one. The exit code names the class: usage is 2, not_found 3, auth 9, forbidden 10, unavailable 11, provider_rejected 12, and everything else 1. LUA_DEBUG=1 lua <command> prints the stack under that line, and lua status --json --ci shows the credential, the agent, and per-primitive drift without changing anything. With --json, only lua workflows, lua auth sessions, and lua marketplace replace the line with { "success": false, "error": { "code", "statusCode", "message", "issues" } } on stdout; every other command keeps the stderr line. Problems inside a deployed agent are a logs question: see Read logs and debug an agent.
Verified against lua-cli 3.33.0.
Exit codes
Branch on the exit code first: 9, 10, and 11 are never fixed by changing code, and 2 is always a flag or argument. The full table, including thelua workflows run outcomes 4 to 8, is on Errors and exit codes.
Authentication
✖ auth: No Lua CLI authentication found. Run `lua auth configure` or set LUA_API_KEY.
Cause. Exit 9. No LUA_API_KEY in the environment or .env, no user session, and no stored key. Fix. Run lua auth configure --email [email protected], then the same command with --otp <code>; or export LUA_API_KEY.
✖ auth: Your Lua CLI session was signed out.
Cause. Exit 9. The user session ended elsewhere: lua auth logout --all on another device, lua auth sessions revoke, or an admin dashboard sign-out. Fix. Run lua auth configure again.
✖ auth: Authentication failed. Your Lua credential may be invalid or expired.
Cause. Exit 9. The server refused the key: revoked, expired, or pasted with a stray character. Fix. Create a key in the admin dashboard (lua admin), then lua auth configure --api-key <key>.
✖ auth: Access denied for this agent: …
Cause. Exit 9. The credential is valid but cannot reach the agentId in lua.skill.yaml: another organization’s agent, a deleted one, or a file copied from another project. Fix. lua agents lists what the credential can reach; lua init --agent-id <id> --force re-points the project.
✖ forbidden: Access denied (403): …
Cause. Exit 10. The credential’s role cannot perform this action on this agent, for example a key issued in another organization. Fix. Ask an organization owner for access, or issue the key from the organization that owns the agent.
Project setup
✖ usage: Project already initialized with agent <agentId>
Cause. Exit 2. lua.skill.yaml already points at an agent and lua init ran non-interactively. Fix. Start in an empty directory, or pass --force to replace the configuration.
✖ forbidden: Scoped CLI credentials cannot create a new agent. …
Cause. Exit 10. lua init --agent-name or --from-agent-id ran with a scoped API key. Fix. Create the agent with a user session (lua auth configure --email …) or in the admin dashboard, then lua init --agent-id <id>.
✖ usage: No lua.skill.yaml found — run this command from a Lua project directory.
Cause. Exit 2. The working directory is not a project. Fix. cd into the project, or run lua init. ✖ usage: Missing agentId in lua.skill.yaml. is the same class: run lua init to select the agent.
Compile
✖ compile_failed: Compilation failed — see errors above.
Cause. Exit 1, after a ❌ Compilation failed: block listing <file>:<line> - <message> per error. Fix. Fix the listed errors; lua compile --verbose adds context and --debug prints the bundler output.
No entry point found in <dir>. Expected one of: index.ts, src/index.ts, agent.ts, src/agent.ts, main.ts, src/main.ts
Cause. No file exports the LuaAgent. Fix. Put export default new LuaAgent({ … }) in src/index.ts; see Project structure.
Invalid tool name "<name>". Tool names can only contain alphanumeric characters, hyphens (-), and underscores (_). …
Cause. A name such as get weather or get.weather. Fix. Use snake_case, for example get_weather. Tool must have an execute function comes from the same validator.
Webhook `secret` must be a string literal or a compile-time-resolvable constant …
Cause. secret: process.env.WEBHOOK_SECRET or another runtime expression on a LuaWebhook. Fix. Write a literal; the secret is read at compile time and never travels in a backup. See Handle a webhook.
agent references <kind> "<name>" but <file> does not define a matching primitive
Cause. A warning: the file the agent imports does not export a primitive with that name, so nothing is bundled and lua test cannot find it. inline "new <Class>({...})" in agent.<property> cannot be bundled is the same problem for a primitive constructed inline. Fix. Export the primitive as a named declaration and register that export on the LuaAgent.
Test
✖ usage: Type must be specified when using the --name option.
Cause. Exit 2. lua test --name … without a type. Fix. lua test skill --name <tool-name> --input '<json>'.
✖ not_found: Tool "<name>" not found
Cause. Exit 3. --name is a skill name or a misspelling; for lua test skill it must be the tool’s name. Fix. Run lua test skill without flags to see the compiled tool list.
✖ usage: Invalid JSON input: …
Cause. Exit 2. --input is not valid JSON, usually because the shell consumed the quotes. Fix. Wrap the JSON in single quotes and pass the tool’s fields directly.
{ status: 'error', error: '<message>' } as the output of lua test
Cause. Your execute threw. The local runner catches it and returns this object, so the command still prints ✅ Tool execution successful! and exits 0. Fix. Read error, fix the code, re-run. In a script, add --json and test with jq -e 'type != "object" or .status != "error"'.
Push
✖ error: Interactive prompt required but --ci flag is set. Provide all required flags or arguments.
Cause. Exit 1. Under --ci the command needed a prompt: more than one entity of that type without --name, a confirmation without --force, or a version without --set-version. Fix. Pass the missing flag; see Automate releases in CI.
✖ error: The "all" type requires the --force flag
Cause. lua push all or lua deploy all without --force. Fix. Add --force; it is the confirmation.
✖ error: Invalid version format: "<value>". Use semantic versioning (e.g., 1.0.5)
Cause. --set-version is not x.y.z. Fix. Pass three dotted integers, or omit the flag and let --force bump the patch version.
✖ error: <kind> "<name>" is not pushed: …
Cause. The server refused the version; the reason follows, with validation issues listed beneath. already exists means that version number was pushed before. Fix. Fix the listed issues; for a version conflict, lua push <kind> --force bumps the patch version.
✖ not_found: <Kind> "<name>" (<id>) no longer exists on the server
Cause. Exit 3. lua.skill.yaml still carries an ID the server has deleted. Fix. Remove that <kind>Id: line from lua.skill.yaml and push again; the compile step registers the primitive afresh and writes the new ID.
✖ unplaced_step: workflow "<name>" is not pushed: createStep "<id>" … placed in no workflow (WORKFLOW_UNPLACED_STEP)
Cause. Exit 1. A createStep in the workflow’s file is never chained into the graph. Fix. Add it with .then(step) or inside .parallel([...]), or delete it. See Author a workflow.
Deploy and promote
✖ error: No versions found for <Kind> "<name>". Push it first using: lua push <type>
Cause. lua deploy on a primitive that has never been pushed; <Kind> "<name>" is missing its ID. Please push it first … is the same situation seen from lua.skill.yaml. Fix. lua push <type> --ci --force --name <name>, then deploy.
✖ error: Version "<version>" not found.
Cause. --set-version names a version the server does not have; the five newest are printed above the line. Fix. Pass one of them, or latest.
✖ error: No backup exists for this agent. Run `lua push` first, or pass `--auto-push` to push and snapshot in one step.
Cause. lua version create needs a source backup to link. Fix. lua push all --ci --force first, or lua version create --auto-push.
Sync and pull
✖ error: Operation failed after Total: <n> component(s) with drift
Cause. Exit 1. lua sync --check found differences between local code and the server, itemized above the line. Fix. lua sync --push to send local state, lua sync --pull to take the server’s, or lua sync to decide per item; see the lua sync reference.
❌ Refusing to pull — <n> local file(s) have uncommitted changes since your last push:
Cause. lua sync --pull would overwrite files you changed after the last backup. Fix. lua push backup to save them, or lua sync --pull --force to discard them; see Back up and restore agent source.
Workflow runs
EFFECT_IN_DOUBT
Cause. A once() call in a code step found a claim from an earlier attempt of the same key that was never settled, so the platform cannot tell whether the effect happened; the step parks and the engine does not retry it. Fix. Check the external system, then lua workflows resolve-step <run-id> --step <id> --outcome complete|skip|fail; retry-step re-runs under the same occurrence and meets the same unsettled claim.
STEP_NOT_PARKED
Cause. Exit 1 (HTTP 409). retry-step or resolve-step named a step that is not in a park those verbs act on; the response carries the step’s status. Fix. Read status: running or pending means wait, an approval or signal park means approve or signal, and a step already decided answers 200 with the standing decision.
PAYLOAD_MISMATCH
Cause. Exit 1 (HTTP 409). approve decided on, or edited, an approval payload that changed after you read it, or lost a race with another decision; the response carries the current payloadFingerprint and editRevision. Fix. Re-read it with lua workflows approval-payload <run-id> --approval <wfa_id>, then re-issue approve with the current --fingerprint <f>.
RUNS_IN_FLIGHT
Cause. Exit 1 (HTTP 409). Either lua workflows delete <name> while runs of the workflow are not terminal (the response counts them), or start on a workflow with concurrencyPolicy: 'forbid' while a run is in flight (the response names the blocking run). Fix. For a delete, wait or pass --force, which cancels the runs in two stages and then deletes. For a start, wait for the blocking run or cancel it; a new idempotency key does not get past the guard.
Runtime
✖ unavailable: fetch failed
Cause. Exit 11. The API or the network failed; the hint reads The Lua API could not be reached — check your network and https://status.heylua.ai, then retry. Fix. Retry after checking the status page and any proxy; a 503 variant names the service behind the API and a request ID to quote to support.
✖ provider_rejected: …
Cause. Exit 12. The model provider refused the request: an invalid bring-your-own key, an unknown model code, or an exhausted quota. Retrying unchanged fails identically. Fix. Follow the hint; lua models list --json shows the codes your organization can use and lua models set --model <code> changes the agent’s model.
Execute function failed after <n> ms: <error> in lua logs
Cause. Your tool, webhook, job, or processor threw in production; the entry’s subType is error. Fix. Reproduce with lua test using the input from the preceding Calling tool with input entry.
searchText must be a string
Cause. Deployed code passed an options object as the third argument of Data.create or Data.update; the deployed runtime accepts only a string there, although lua test accepts both. Fix. Pass searchText as a plain string; see Data.
Still stuck
Write to [email protected] with the command you ran, its output underLUA_DEBUG=1, the output of lua --version and lua status --json --ci (remove organization names you do not want to share), and the agent ID from lua.skill.yaml. For runtime problems, add the id and timestamp of the lua logs --json entry.