Command troubleshooting
Start with the job’s record in Command history. 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 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.
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. 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 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 for the supported input forms.
Cancelling a command
The CLI has no cancel command. In the console, open Command history 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 |