Troubleshooting
Common issues and how to resolve them.
| Symptom | Likely Cause | Fix |
|---|---|---|
| Agent won't connect | WebSocket blocked by firewall or proxy | Check that port 443 outbound is open. Try spectral serve --verbose for connection logs. |
| "Authentication failed" | Expired or invalid token | Run spectral login to refresh your auth token. |
| Commands timeout | Long-running process or missing dependency | Check if the command needs user input. The agent has a default timeout; use more specific prompts to narrow the scope. |
| Agent can't find files | Wrong project directory or file doesn't exist | Make sure spectral serve is running in the project root. Use ls or find in the chat to verify paths. |
| "Permission denied" errors | File system permissions | The agent runs with your user permissions. Check chmod on the files it's trying to access. |
| Node.js version too old | Node.js < 20 | Run node --version. Install Node.js 20+ from nodejs.org. |
| Port already in use | Another process on the relay port | The default port is configurable. Kill the conflicting process or use a different port with --port. |
| WebSocket disconnects frequently | Unstable network | The agent auto-reconnects with exponential backoff. Check your network stability or VPN connection. |
Still stuck?
Check the Agent overview for architecture details, connection modes, and supported platforms.