Troubleshooting

Edge Connector Support

This page covers the most common issues encountered when setting up and operating the Edge Connector, along with diagnostic steps and frequently asked questions.

Common issues

Connection refused

Symptom: The Edge Connector logs ECONNREFUSED or fails to connect to the nara platform server.

Causes and solutions:

• Platform server is not running. Verify the server is started and reachable.
• Wrong URL. Check TOOL_RPC_URL in your environment or config.json. Production uses wss:// with a public hostname.
• Firewall or proxy blocking. Ensure outbound WebSocket connections are allowed on the target port. Check corporate proxies that may not support WebSocket upgrade.
• Port mismatch. Confirm the platform server is listening on the port specified in your URL.

Authentication failed

Symptom: Token validation failed, Token has expired, or No authentication token found.

Causes and solutions:

• Token expired. JWT tokens have an expiration time. Re-authenticate with edge-connector auth --browser or edge-connector auth --token <new-token>.
• Token file missing. Check that auth-token.json exists at the path specified in config.json or AUTH_TOKEN_PATH. Verify the path is correct.
• No organization in token. The JWT must contain an orgId claim or an orgs map. Ensure you are logged into an organization in the nara webapp before generating the token.
• Deployment credentials invalid. If using DEPLOYMENT_ID and DEPLOYMENT_SECRET, verify both values are correct and the deployment exists in the admin panel.

Bundle sync failed

Symptom: Bundle sync error or tools are not updating after an upload.

Causes and solutions:

• Not connected to the platform. Bundle sync requires an active WebSocket connection. Check the connection status via curl http://localhost:8080/statusz.
• No bundle assigned. Verify a bundle is assigned to your deployment. Use edge-connector bundle list to check. Set a default bundle with edge-connector bundle set-default.
• Network issue. The download may fail due to intermittent connectivity. The sync retries automatically every 10 minutes.
• Checksum mismatch. If the local checksum already matches the server, no download occurs. Force a re-sync by deleting the local manifest.json and dist/ directory, then restart.

Tool execution timeout

Symptom: Tool calls return a timeout error or the agent reports the tool did not respond.

Causes and solutions:

• Slow implementation. Review your tool code for blocking operations, long network calls, or infinite loops. Consider adding timeouts to external API calls.
• Implementation error. An unhandled exception in your tool code may cause it to hang. Wrap all logic in try/catch and return structured error objects.
• Resource exhaustion. Check CPU and memory usage on the Edge Connector host. Heavy tools may need more resources.

Health check failing

Symptom: GET /healthz returns 503 or the health endpoint is unreachable.

Causes and solutions:

• Port conflict. Port 8080 may be in use by another service. Set a different port via the HEALTH_PORT environment variable.
• Not yet connected. /healthz returns 503 until the Edge Connector has successfully connected to the platform server. Check /statusz for details.
• Process not running. Verify the Edge Connector process is active. Check for the edge-runtime.lock file.

Process lock conflict

Symptom: Edge runtime already running (pid ...) on startup.

Causes and solutions:

• Another instance is running. Only one Edge Connector runtime can run per installation directory. Stop the existing instance before starting a new one.
• Stale lock file. If the previous process crashed without cleaning up, the lock file may be stale. Delete edge-runtime.lock from the installation directory and try again.
• Multiple installations. If you need multiple Edge Connectors, use separate installation directories and different deployment IDs.

WebSocket disconnects

Symptom: Frequent Disconnected from platform server messages in the logs.

Causes and solutions:

• Unstable network. The Edge Connector automatically reconnects with exponential backoff. Occasional disconnects on unreliable networks are normal.
• Proxy timeout. Some proxies close idle WebSocket connections. The 30-second heartbeat should prevent this, but aggressive proxies may need configuration changes.
• Server restart. When the platform server restarts (e.g., during deployments), all connections drop. The Edge Connector reconnects automatically.
• Deployment conflict. If another instance of the same deployment connects, the server may reject the duplicate. Check for Deployment already connected in the logs.

Diagnostic steps

When troubleshooting an issue, follow these steps to gather information and isolate the problem.

1. Check the runtime logs

   The Edge Connector prints detailed logs to stdout. Look for error messages, connection status changes, and tool execution results. Key log patterns:

   • Connected to platform server — successful connection
   • Disconnected from platform server — connection lost
   • Token validation failed — authentication issue
   • Bundle sync error — bundle download problem
   • Tool "..." invoked but not available — missing implementation

2. Verify authentication

   Confirm the token is valid and the organization is correct:

   edge-connector bundle list

   If this returns an error, re-authenticate:

   edge-connector auth --browser

3. Test the connection

   Check if the platform server is reachable:

   curl -v http://localhost:3001

   For connector status details, use the runtime health checks:

   curl http://localhost:8080/statusz

   See the Runtime page for the meaning of each health and status endpoint.

4. Check the health endpoint

   # Liveness (is the process running?)
   curl http://localhost:8080/livez
   
   # Readiness (is it connected and ready?)
   curl http://localhost:8080/healthz
   
   # Full status
   curl http://localhost:8080/statusz

5. Inspect the configuration

   Verify your config.json and environment variables:

   • Is toolRpcUrl correct?
   • Is authTokenPath pointing to a valid token file?
   • Is platformApiUrl set for your environment?
   • Are DEPLOYMENT_ID and DEPLOYMENT_SECRET set (for server mode)?

6. Check the lock file

   If the runtime refuses to start, check for a stale lock:

   cat edge-runtime.lock

   If the PID listed is not a running process, delete the file and try again.

Frequently asked questions

How often does bundle sync happen?

The Edge Connector checks for bundle updates every 10 minutes via a periodic poll. Additionally, the platform server can push a real-time notification when a new bundle version is uploaded, triggering an immediate sync. You do not need to restart the Edge Connector to pick up new tool implementations.

Can I run multiple Edge Connectors?

Yes, but each instance must use a separate installation directory and a different deployment ID. The process lock (edge-runtime.lock) prevents multiple instances from running in the same directory. Each deployment can have its own bundle assignment, allowing different Edge Connectors to run different sets of tools.

What happens if the connection drops?

The Edge Connector automatically reconnects with exponential backoff. The initial retry delay is 5 seconds, doubling with each attempt up to a maximum of 60 seconds. Once reconnected, tools are re-registered with the platform server. During the disconnection period, tool execution requests for this connector will fail with a “connector unavailable” error on the platform side.

How do I update tools on a running connector?

Upload a new bundle version using edge-connector upload. Connected Edge Connectors will detect the update either through a server-pushed notification (immediate) or during the next periodic sync (within 10 minutes). The update is applied atomically:

1. New tool files are downloaded to a staging directory.
2. The existing dist/ directory is swapped with the staging directory.
3. The tool executor reloads implementations from the new files.
4. Tools are re-registered with the server.

No restart is required.

What ports does the Edge Connector use?

Port	Protocol	Direction	Purpose
Platform server (configurable, typically 443)	WebSocket	Outbound	Connection to the nara platform server
8080 (configurable via HEALTH_PORT)	HTTP	Inbound	Health check endpoints (/livez, /healthz, /statusz)

Can I run the Edge Connector in a Docker container?

Yes. Set EC_DISABLE_TRAY=1 and EC_DISABLE_AUTOSTART=1 since system tray and OS-level autostart do not apply in containers. Use DEPLOYMENT_ID and DEPLOYMENT_SECRET for authentication. Configure Kubernetes liveness and readiness probes to point at /livez and /healthz on the health port.

How do I check which tools are registered?

After the Edge Connector connects, it logs the list of registered tools:

Registered tools: getSystemInfo, getResourceUsage, getTopProcesses

You can also check the /statusz health endpoint or look at the bundle status:

edge-connector bundle status

What is the maximum bundle size?

The maximum bundle size is 50 MB. This limit is enforced during the upload step. If your bundle exceeds this limit, consider reducing the number of inlined dependencies or splitting tools across multiple bundles.

Getting help

If you cannot resolve an issue using this guide:

Configuration Reference Review all configuration options and their defaults.

CLI Reference Check command syntax and available options.

Runtime Behavior Understand the startup sequence, reconnection logic, and sync behavior.

Tip

When reporting an issue, include the output of curl http://localhost:8080/statusz, your config.json (with secrets redacted), the relevant log output, and the Edge Connector version (edge-connector --version).