Troubleshooting
Where to look
Section titled “Where to look”- Launcher and runtime logs:
<installDir>/logs/launcher.logand<installDir>/logs/runtime.log(rotated at 10 MB). - Autostart process output:
~/.edge-connector/stdout.logand~/.edge-connector/stderr.log. - Connector state:
~/.edge-connector/state.json. - Live status:
http://localhost:8080/statusz— shows connection state, the last connection error, and webhook relay state.
Authentication errors
Section titled “Authentication errors”No authentication token found. Run: edge-connector auth — the connector has no saved token. Run edge-connector auth and complete the browser or token flow.
Invalid token format - unable to decode JWT, Token has expired, or Token must include organization information (orgId or orgs) — the token passed with auth -t is malformed, expired, or missing organization claims. Obtain a fresh token or use the browser flow (auth -b).
Timed out waiting for desktop auth — the browser approval was not completed within the 2-minute limit. Restart the flow and click Approve on the verification page promptly.
Connection problems
Section titled “Connection problems”Unable to connect to the Tool RPC server. — verify the server is reachable and the WebSocket URL is correct (toolRpcUrl in config.json or the TOOL_RPC_URL override). The runtime retries with backoff (5 s base, doubling, capped at 60 s, up to 10 attempts).
Deployment already connected from another instance! — another connector is already connected with the same deployment identity. Stop the other instance, or provision a separate deployment for this machine.
Edge runtime already running (pid …) — a process lock (<installDir>/edge-runtime.lock) indicates a running runtime. Stop the existing process before starting a new one; if it crashed, remove the stale lock file.
Bundle and packaging errors
Section titled “Bundle and packaging errors”No tool source files found in tools/... — the packager expects one file per tool under tools/; a single index.ts entrypoint is not supported. Regenerate stubs with edge-connector generate.
Bundle too large: <n>MB (max 50MB) — the bundle exceeds the upload limit. Remove unnecessary dependencies or assets from the implementations project.
Launcher log entries about rollback, No valid runtime available, or download/extract failures indicate a failed self-update — the launcher automatically rolls back to the previous runtime; check launcher.log for the cause.
Tool execution errors
Section titled “Tool execution errors”Tool "<name>" is not available on this deployment — the tool is not part of the bundle assigned to this deployment. Check the assignment with edge-connector bundle status and bundle tools, or assign the right bundle with bundle assign.
requires execution context — the tool needs an execution context that the current invocation did not provide.