> ## 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. # Troubleshoot the CLI > Diagnose a failing lua command from its exit code and error line, then fix it by stage Every failed command ends with one stderr line, `✖ : `, 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 ` 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](/ship/logs-and-debugging). *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 the `lua workflows` run outcomes 4 to 8, is on [Errors and exit codes](/reference/cli/errors-and-exit-codes#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 you@example.com`, then the same command with `--otp `; 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 `. ### `✖ 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 --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 ` **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](/concepts/credentials). **Fix.** Create the agent with a user session (`lua auth configure --email …`) or in the admin dashboard, then `lua init --agent-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 `: - ` per error. **Fix.** Fix the listed errors; `lua compile --verbose` adds context and `--debug` prints the bundler output. ### `No entry point found in . 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](/get-started/project-structure). ### `Invalid tool 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](/build/handle-a-webhook). ### `agent references "" but 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 ({...})" in agent. 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 --input ''`. ### `✖ not_found: Tool "" 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: '' }` 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](/ship/ci-and-automation). ### `✖ 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: "". 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: "" 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 --force` bumps the patch version. ### `✖ not_found: "" () no longer exists on the server` **Cause.** Exit 3. `lua.skill.yaml` still carries an ID the server has deleted. **Fix.** Remove that `Id:` line from `lua.skill.yaml` and push again; the compile step registers the primitive afresh and writes the new ID. ### `✖ unplaced_step: workflow "" is not pushed: createStep "" … 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](/build/workflows/authoring). ## Deploy and promote ### `✖ error: No versions found for "". Push it first using: lua push ` **Cause.** `lua deploy` on a primitive that has never been pushed; ` "" is missing its ID. Please push it first …` is the same situation seen from `lua.skill.yaml`. **Fix.** `lua push --ci --force --name `, then deploy. ### `✖ error: 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: 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](/reference/cli/sync). ### `❌ Refusing to pull — 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](/ship/backups-and-restore). ## 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 --step --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 --approval `, then re-issue `approve` with the current `--fingerprint `. ### `RUNS_IN_FLIGHT` **Cause.** Exit 1 (HTTP 409). Either `lua workflows delete ` 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 ` changes the agent's model. ### `Execute function failed after ms: ` 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`](/reference/sdk/data). ## Still stuck Write to [support@heylua.ai](mailto:support@heylua.ai) with the command you ran, its output under `LUA_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.