---
title: "Command troubleshooting"
description: "Find out why an Alpacon command was refused, held, or stopped. Match messages and exit codes to recovery steps, including verified file execution failures."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# Command troubleshooting

Start with the job's record in [**Command history**](/use/audit/events/commands/). Check whether it ran before submitting it again.

## Exit codes

| Exit code | Meaning |
| --- | --- |
| 1 | General failure, including stuck, error, cancelled, client wait timeout, or inline credentials |
| 2 | CLI usage error |
| 3 | Work-session access refused |
| 4 | Waiting for command or sudo approval |
| 6 | Rejected or not approved before the request expired |
| 7 | Purpose required, if your workspace asks for one |
| Remote exit code | The finished command's result; 124 indicates the server run-time limit |

`exec logs` also exits 0 when a command is still running. Read the status, not just the exit code. See [run a command](/use/work-sessions/commands/run/) for its outcomes. Exit 5 is a server-busy code for other CLI operations, not exec.

## Refused before it runs

| Message | Action |
| --- | --- |
| `line: Ensure this field has no more than 2048 characters.` | Shorten the command or use verified file execution |
| `--purpose is limited to 2000 characters; the server refuses a longer one` | Shorten the purpose to at most 2000 characters |
| `--purpose requires a value describing what this command is for` | Supply a non-empty purpose |
| `server rejected this command—the command line carries a credential` (`command_inline_credential`) | Move credentials to `--env` |
| `command_dangerous_env` (no dedicated CLI message) | Remove the refused variable |
| `invalid --env argument: use --env=KEY or --env=KEY=VALUE` | Use `--env=KEY` for a variable already set in your shell, or `--env=KEY=VALUE` |
| `target server is not in this session` (`work_session_server_not_allowed`) | Choose an included server or request access to the target server |

The console shows its own wording for these errors; with `--output json`, the CLI shows the error code.

For other work-session refusals, see [gate errors](/reference/cli/work-session/#gate-errors).

## Held or rejected

A command at **Awaiting approval** waits for a person to decide. If your workspace asks for a purpose, answer for the same job with `alpacon exec purpose JOB_ID PURPOSE`.

For **Rejected**, inspect **Rejection reason** in the audit side panel. See [understanding a rejection](/use/audit/events/commands/#understanding-a-rejection). A held command runs automatically if approved; do not submit a duplicate while it waits.

| Message | Action |
| --- | --- |
| `This command carries a script body; resubmit the script as a file execution` (`use_file_execution`) | Where a workspace rule blocks scripts in command lines, the command is created and then shows **Rejected**. Resubmit the script as a [file execution](/use/work-sessions/commands/file-execution/) with `alpacon exec --file …`, targeting only the rejected servers that support file execution. A multi-server file execution is refused with `file_exec_unsupported_agent` if any target lacks support. |

## Stopped, timed out or still running

| Message | Action |
| --- | --- |
| `agent never acknowledged the command (likely disconnected)` | Check the server's connection and the job record before resubmitting; an offline server can leave a command queued |
| `command failed: [agent_timeout] agent acknowledged the command but did not return a result in time (status=stuck)` | Foreground exec exits 1 after 10 minutes, but the command can keep running for up to 30 minutes. Check the same job with `exec logs`; use `--detach` for future runs that may exceed about 10 minutes |
| `Command timed out after 30m0s` | The server's 30-minute limit was reached. Split the work before retrying |
| `Error: [client_timeout] CLI gave up waiting for the server to report a result` | The CLI stopped waiting without cancelling the command. Check the same job before retrying |

## File execution refusals

| Message | Action |
| --- | --- |
| `the server refused the file: it is empty, and a verified file needs content to hash` (`file_exec_empty_content`) | Supply a non-empty script |
| `the server refused the file: a verified file is limited to 65536 bytes (64 KB)` (`file_exec_content_too_large`) | Reduce the script to 64 KB or less |
| `the interpreter, the path and the arguments together exceed the server's command line ceiling` (`file_exec_line_too_long`) | Shorten the interpreter, path, or arguments to fit 2048 characters together |
| `the server refused the file path or the interpreter: both must be absolute paths starting with /` (`file_exec_invalid_path`) | Use absolute paths for both |
| `the server refused the request: environment variables are not allowed on the file lane` (`file_exec_env_not_allowed`) | Remove `--env`; let the script read required values on the server |
| `the server refused the reuse proposal: a reuse duration must be 1 to 366 days` (`file_exec_invalid_reuse_days`) | Use 1–366 for `--reuse-days`, or omit it |
| `the server refused the reuse proposal: this workspace's file execution grant ceiling is shorter than the duration proposed` (`file_exec_reuse_exceeds_max`) | Stay within the workspace ceiling or omit `--reuse-days` |
| `this deployment has the command assessor disabled, so '<server>' cannot run a verified file` (`file_exec_assessor_disabled`) | Ask the administrator to enable AI review |
| `the agent on '<server>' does not offer the file lane; it needs Alpamon 2.8.3 or newer on a platform that has the file lane` (`file_exec_unsupported_agent`) | Ask the administrator to check server support; see the CLI reference |
| `the file changed after it was verified, so the agent refused to run it` (`file_hash_mismatch`) | Review and submit the contents you intend to run, then keep the server file unchanged until execution |
| `this server's platform cannot run a file execution safely` (`file_exec_unsupported`) | Use a server that supports verified file execution |
| `the file is larger than the agent will run` (`file_too_large`) | Check the server file and submit a matching script within the 64 KB input limit |

See [verified file execution](/reference/cli/exec/#verified-file-execution) for the supported input forms.

## Cancelling a command

The CLI has no cancel command. In the console, open [**Command history**](/use/audit/events/commands/) and use **Cancel scheduled command** to cancel a command that has not been delivered. This action appears only while the command can still be cancelled.

| Message | Action |
| --- | --- |
| "This command has already been sent to the server." (`event_command_already_sent`) | Check its result; cancellation cannot recall a delivered command |
| "Commands that apply firewall rules can't be cancelled." (`event_command_not_cancellable`) | Check the firewall operation and its result instead of trying to cancel it |

Source: https://docs.alpacax.com/use/work-sessions/commands/troubleshooting/