When a run does not work
Separate environment problems, unavailable tools and unverified outcomes so the next step addresses the actual issue.
On this page · 9 sections
Find the earliest failed dependency
Start with the first observable failure, not the last visible symptom. An empty response in a visual interface may originate in the interface connection, runtime authentication, model availability or an individual tool. Each layer needs different evidence and a different next step.
Record the command or action, the expected observation and the actual result. Change one relevant condition at a time, then repeat the smallest diagnostic that tests it. A successful restart is useful only if it changes the failed condition. Avoid broad reinstalls, permission changes or production edits before narrowing the problem.
| Observation | Start here |
|---|---|
| Import or startup error | Python environment and entry point. |
| Connection or authorization error | Runtime URL, local listener and configured access. |
| Model unavailable | Inference endpoint and selected model. |
| Task ran but result is uncertain | Executed checks and remaining acceptance criteria. |
The command cannot start
Confirm that you are in the repository root and using its configured Python environment. Module or dependency errors occur before the agent can do useful project work. Preserve the error message and compare it with the setup instructions for your branch.
Do not repeatedly restart a failing command without changing the condition that caused the failure.
The run is looking at the wrong project
Confirm the workspace displayed by the CLI and the path supplied with --workspace. Its default is the launch directory. Starting from the runtime repository without an explicit workspace can therefore inspect the runtime instead of your application. Quote paths containing spaces and check that the directory exists.
If a file tool reports an out-of-scope path, inspect the intended target rather than broadening permissions immediately. The file may be outside the selected project, or the task may refer to a path from a different checkout. A path error is not proof that the file should be accessible. Resolve ownership and scope before changing the boundary.
The model service is unavailable
Check the configured endpoint and whether the selected model service is running. A running interface does not prove inference is available. Do not interpret a website example as a response from the local runtime.
If you change the endpoint, review the data path as well as connectivity. Sending project material to a remote service is not just a performance setting.
The interface cannot reach its runtime
For the server-backed path, inspect the configured interface URL and the local server’s health endpoint. The default runtime port is 9090, but a custom AROXA_PORT setting changes it. Read the actual connection error before assuming that the server is absent or that the model is slow.
An origin or authentication error means the process may be reachable but rejecting the request. Check the intended configuration; do not remove origin checks or expose the development listener as a workaround. The health response’s inference fields also distinguish a reachable runtime from an available model. Keep those results separate in the diagnosis.
curl --max-time 5 http://127.0.0.1:9090/healthA tool or connector is missing
Confirm which tools are actually registered for this entry point and whether a connector is configured and reachable. Tool availability can differ across environments. An unavailable tool should remain an explicit limitation in the run.
Use an available, authorized alternative when appropriate. Do not fabricate the result of an operation that did not run.
An operation was declined or isolation is unavailable
A declined approval is not a tool execution failure: the operation did not receive permission to run. Review the exact request and target. If the requested operation is unnecessary, choose a smaller authorized check; do not retry it through another interface to evade the decision.
Requested Docker execution can fail when Docker is unavailable. Current tooling does not silently promise filesystem isolation in that case. An explicit fallback changes the boundary to host execution and should not be enabled merely to remove the error. Preserve the isolation requirement or stop and report the missing dependency. The permissions guide explains why a workspace restriction alone is not enough.
The outcome is still uncertain
Read the executed checks and their outputs. A successful process may have checked less than the task requires. Narrow the remaining question and run a relevant check before accepting a completion claim.
If you ask for help, share the entry point, a concise reproduction and the relevant error. Remove credentials and confidential project material before sending it.
Share a minimal, redacted reproduction
A useful report includes the entry point, source version if known, workspace type, the smallest reproduction and the relevant error text. Describe what you expected and what actually happened. If the operation might have changed state, include what you inspected before trying again.
Review the excerpt before sharing it. Remove tokens, credentials, private source, personal details and model-service addresses that should remain confidential. State which checks you could not run rather than filling their gaps with assumptions. Another person should be able to identify the failing layer without receiving your full repository or the entire run history.
- Which interface and command were used?
- What was the expected result and the first actual failure?
- Which configuration facts can be shared safely?
- Did any files or external state change?
- What check was tried, and what remains unknown?