Skip to main content
Start with resolved configuration and connectivity:
For a sandbox problem, also run atonom eval -c 'return 1' --json. status checks the platform API only.

​
CLI not found

Install the binary supplied by the Atonom team and make sure its directory is on your shell’s PATH. If you used the macOS installation steps, add $HOME/.local/bin to PATH and open a new terminal. See Install & connect.

​
Missing base URL or sandbox URL

Set base_url for platform commands and lua_service_url for eval. Check for higher-priority environment variables or flags. Local config is selected from the nearest ancestor workspace, so confirm the reported workspace_root.

​
401: credentials rejected

Run atonom login for the configured host. If ATONOM_TOKEN is set, it overrides device credentials and is not refreshed. Remove or replace the expired override. Do not expose the token while diagnosing the environment.

​
403: permission denied

Your account needs permission to edit Lua tools. Confirm that you are signed in to the correct Atonom environment and ask your administrator to check your access.

​
404: tool or service not found

Check your Atonom URL and verify that the tool ID appears in atonom list. If the error persists, contact the Atonom team with your CLI version, the command that failed, and the error message. Do not include credentials.

​
No Atonom agents / multiple Atonom agents

Creating a tool requires an existing Atonom agent. If none is available, create one through the platform. If there are several, choose one interactively or pass --comm-agent-id ID; JSON mode cannot prompt for a selection.

​
Pull succeeded but my file did not change

Inspect results[].action. skipped-local-edits means your local file was protected. skipped-no-script means the tool has no stored script body. Pull can exit zero in both cases. Back up edits before intentionally forcing an overwrite.

​
File is not linked / no local file

Use the tool ID from atonom list, then atonom pull ID. For a deliberate new local file, pass --tool-id ID. Keep files inside scripts_dir to persist their links. eval needs an actual file path relative to your current directory, even when run accepts a bare scripts-directory filename.

​
409: remote changed

Someone changed the remote since your last sync. Preserve local edits, inspect diff, refresh the baseline, and reapply the changes. Follow the conflict workflow. A default run is not a conflict-resolution mechanism.

​
Eval returns null instead of my transform result

A raw chunk that only defines transform does not call it. Add --transform '{...}'. For a raw chunk, return the intended value at top level. Do not combine a top-level return with the transform wrapper.

​
Exit 2: FAIL / script error

Inspect outcome.error for eval or error for run. Check syntax, required keys, value types, missing libraries, and resource limits. A code 2 with usage text instead of JSON is an argument-parser error. A failed default run may already have saved the script; inspect saved.

​
Exit 3: unanswered trap

Provide a --trap-result for every expected host call in order. Inspect unanswered_trap for the missing call. If the cap was reached, verify loop termination before raising --max-traps. --trap-echo can test wiring but may not match a real capability’s response shape.

​
Empty arrays become objects / null disappears

Use atonom.json.array() for an empty array and atonom.json.null for a null table field. Empty {} is an object, and assigning nil removes the field.

​
Eval passes but platform execution fails

Mocks do not validate live capability availability, permissions, schema configuration, or external behavior. Confirm the stored script is current, the input schema matches, and the owning agent has the required capabilities. If the same inputs still behave differently, share the script and error with the Atonom team.

​
Timeout or connection refused

Check your sandbox URL and follow the connection instructions supplied by the Atonom team. An HTTP timeout (--timeout-secs, default 120) differs from the sandbox’s CPU limit. Raising it will not fix an infinite loop, memory exhaustion, or a missing service.