Troubleshooting

Installation Issues

Install script fails: Node.js version too old

Install script fails: git is not installed

pilotdeck command not found

npm install fails

Desktop App Issues

PilotDeck.app crashes or cannot start

codesign --verify says valid, but the app still will not start

Configuration Issues

Startup error: missing_provider / missing_model

Startup error: invalid_api_key_ref

Config changes do not take effect

PILOT_HOME has no effect

Runtime Issues

Model requests time out

Router Fallback triggers frequently

pilotdeck tui requires an interactive terminal

Cron command requires a running pilotdeck server

Memory cannot retrieve relevant context

WebSocket connection fails

Logs and Diagnostics

Server logs are printed to stdout. Common prefixes:

Prefix	Source
`[always-on]`	Always-On Discovery
`[cron]`	Cron runtime
`[PilotDeck]`	Router retry and fallback
`[runtime]`	Shutdown flow

Startup config diagnostics look like:

[config] warning: deprecated field "agent.fallbackModel", migrate to "router.fallback.default"
[config] error: missing_provider "nonexistent" referenced by agent.model

提示 · Tip

When filing an issue, include node --version, sanitized ~/.pilotdeck/pilotdeck.yaml, server startup logs, and OS version.

Installation Issues​

Desktop App Issues​

Configuration Issues​

Runtime Issues​

Logs and Diagnostics​

Installation Issues

Desktop App Issues

Configuration Issues

Runtime Issues

Logs and Diagnostics