Troubleshooting

Start Here

aegis status
aegis logs core
aegis diagnostics deployment-readiness
aegis diagnostics native-readiness

Common Problems

Symptom	Likely cause	First check
Core is unreachable	Core not started, wrong profile, port conflict	aegis status
Chat cannot plan tools	Provider missing or invalid	provider environment keys and provider status
Worker says it cannot act	Local Gateway not connected or tools not advertised	aegis worker tools --no-exec
Mobile app cannot connect	Wrong Core URL, no LAN/private/tunnel route, token not paired	Core URL and pairing state
Channel receives messages but does not act	Handler should route ordinary prose to Manager, not parse keywords	gateway logs and provider trace
Native app shows missing permissions	OS-level permission not granted	platform Settings / privacy permissions

Mobile Pairing

Mobile devices use scoped native node tokens. They should not store the long-lived owner token.

If pairing fails:

1. Confirm Core URL is reachable from the phone.
2. Confirm the device is on the same trusted network, VPN, Tailscale, or tunnel.
3. Generate a fresh setup link or QR code from the desktop app.
4. Approve the device in Core.
5. Revoke stale device tokens if needed.

When to Use Logs

Use logs to inspect runtime behavior, not to bypass product state:

aegis logs core

For AI tool-use issues, prefer provider trace and tool ledger evidence over guesses from raw logs.