Troubleshooting
Common connection errors
Fixes for the most common startup failures.
Most first-run failures come down to adapter mismatch, missing headers, or the target simply not being reachable.
Diagnostic checklist
- Verify the target URL responds with
curlfirst. - Confirm the adapter matches the agent's contract (see native adapter).
- Add required auth headers with
--header. - Run
talos-scan doctorto validate install + network.
Errors and fixes
| Error | Likely cause | Fix |
|---|---|---|
E_TARGET_UNREACHABLE | Firewall, wrong port, or dead process. | Check with curl; confirm agent is running. |
E_ADAPTER_HANDSHAKE | Response shape doesn't match adapter contract. | Try --adapter native or write a custom adapter. |
E_AUTH_401 | Missing or expired credential. | Pass --header 'Authorization: ...' |
E_GRAPH_EMPTY | Agent exposes no tools Talos can see. | Check tool registration and adapter version. |