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. - Auth token:
~/.edge-connector/auth-token.json— relativeauthTokenPathvalues resolve to this directory; setNARA_DATA_DIRECTORYto move it. - 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 approval window. Restart the flow and click Approve on the verification page promptly. If the message includes last poll error, the connector could not reach the platform while polling — check firewall and proxy rules for direct HTTPS access.
Tray shows “not logged in” and no browser opens — in service mode the connector never opens a browser on its own. Click Login in the tray; the login page opens in the session that clicked.
[Connectivity] ... — after failed platform requests, the connector probes DNS, TCP, and TLS separately and logs which layer dies. Verdicts mentioning hanging DNS, dropped packets, or a stalled TLS handshake indicate a firewall or endpoint-security agent blocking the service process; forward the line to the network team.
Runtime made no progress ... — the watchdog detected a wedged runtime and exited; the service supervisor restarts it automatically. Check the [Connectivity] line logged with it.
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.