Troubleshooting
Resolve configuration, runtime ownership, Queue safety, and compaction errors without automatic replay or disabling security checks.
A Queue or Continue control is disabled
Inspect queue status and the visible cleanup/recovery message. Pending work, an active turn, UNKNOWN admission, or unverified process cleanup can block dispatch. Never clear state or resend the original prompt just to enable a control. Check the originating task’s effects first.
Retry says the turn is ineligible
Retry requires the latest admitted failed or timed-out turn. A completed task, unstarted submission, step-limit stop, or cancelled task is not eligible for that command. Continue is available for eligible stopped or step-limited work. Both refuse unknown tool outcomes.
Compaction fails
Check that no task or Queue work is active. Select a working model and endpoint. Truncated, invalid, incomplete, or ineffective summaries preserve prior context. No automatic summary retry occurs; inspect the sanitized error before choosing whether to make another billed request.
The runtime cannot open the session store
Close the client that owns that store before starting a second runtime. Do not delete lock files from a live session. Use the active client for Queue actions. Do not copy a live session into tests.
Credentials or model are rejected
Confirm the selected provider, model identifier, endpoint, and credential through its official management flow. For custom sessions, supply the custom endpoint again; it is not persisted with credentials in the session. Share sanitized errors only.
macOS blocks the executable
Version 1.0.0 is distributed without Apple Developer ID signing or notarization. Gatekeeper may block the CLI or the extension runtime. Verify the published SHA-256 and source before deciding whether to allow either executable.
After attempting to open the blocked executable, use System Settings → Privacy & Security → Open Anyway, if macOS offers that option, and confirm the specific executable yourself. The CLI and sibling runtime may each need approval. This does not establish Apple review or notarization. Managed Macs may disallow approval; contact your administrator or support if it is unavailable. Do not bypass a malware or damaged-file warning, disable Gatekeeper globally, or remove quarantine attributes as a routine installation step.
Get help
Run gaionix-coder COMMAND --help. In VS Code, use “Gaionix Coder: Copy Diagnostics” and review it before sharing. Contact hello@gaionix.com with version, platform, sanitized error, and a minimal reproduction. Never include credentials, private prompts, or complete session journals.