Docs/Help
Troubleshooting
Fixes for common Gray problems: Gatekeeper, missing models, context overflows, rate limits, cron, plugins, and where the logs are.
Logs first
$tail -f ~/.gray/logs/gray.log$GRAY_LOG=debug gray # the firehose
macOS says the binary can't be verified
Browser downloads get quarantined because the binary is not notarized. Install with the curl one-liner instead, or clear the flag with xattr -d com.apple.quarantine $(which gray).
Nothing happens when I send a message
No provider or model is configured yet. Run /connect, then /model. A key in GRAY_API_KEY or OPENAI_API_KEY beats the stored one — unset a stale export if the wrong key keeps winning.
context_overflow
Gray compacts and retries once on its own. If it still overflows, the window it resolved is probably too large for the model: check /context and set it explicitly, e.g. /context 128k.
rate_limited, server_error, connection_failed
Provider-side. In --json mode these exit with code 3, meaning a retry usually succeeds. Switch model or provider with /model if one stays down.
Cron jobs never fire
Something has to tick the store. Check gray gateway status (exit 1 means down), or run gray cron serve. gray cron run <id> fires a job immediately to test it.
A plugin fails to load
Run gray plugin check <dir> against it, and gray --dump-manifest to see what actually loaded. gray plugin disable <name> takes it out of the way.
Still stuck
/feedback <what happened> saves a local copy and opens a prefilled GitHub issue. Or ask in Discord.
Join the Discord
Chat with the people building and running Gray. Show what you made with it.
Join Discord →