Troubleshooting

This page is organized around what you are likely to see as a user, not around internal components.

Focused troubleshooting pages:

• Troubleshooting Auth
• Troubleshooting Empty States
• Troubleshooting Integrations

grok run Or grok exec Says No xAI Credentials Were Found

What it means:

• Grok Code cannot find a usable xAI API key

What to do:

1. run grok whoami
2. if you are not connected, use grok login or /connect
3. if you rely on env vars, confirm XAI_API_KEY is really set in the shell you launched

/connect Opens In Repair Mode

What it means:

• the stored or provided key is invalid, stale, or otherwise not usable

What to do:

1. press Enter in the repair step
2. paste a fresh xAI API key
3. finish the flow and verify with grok whoami

Auth Looks Fine, But Grok Code Says You Are Rate-Limited

Use:

grok wait

What to expect:

• if Grok Code has recorded rate-limit state before, it shows blocked accounts and wait time
• if a ready backup account exists, the provider can stay usable
• if no blocked state was recorded yet, grok wait has nothing to inspect

A Lane Or Feature Looks Empty

This is often normal.

Examples:

• Gate is empty until a run stages an artifact
• Recall is sparse until you have saved work
• /checkpoint restore has nothing to show until a checkpoint exists
• harness report and diff need previous harness runs
• bench needs a scorecard
• memory and notepads need content before the inspectors become interesting

If you are unsure whether the emptiness is expected, ask:

• have I created the underlying session, artifact, run, or file yet?

export, share, Or replay Cannot Find An Active Branch

What it means:

• there is no active graph-backed branch to operate on

What to do:

• resume a saved run first
• or specify a session directly
• for CLI export and replay, use session@branch when you need a specific branch

Session Or Branch Queries Are Ambiguous

What it means:

• more than one saved session or branch matched what you typed

What to do:

• use a longer id prefix
• use the exact title or branch id
• list sessions first with grok sessions

Checkpoints Do Not Work

Common causes:

• you are not inside a git repository
• there are no changed files to snapshot
• you are trying to restore a checkpoint that does not exist

Useful commands:

• /checkpoint
• /checkpoint save demo
• /checkpoint restore latest

Worktrees Do Not Work

Common causes:

• the project is not a git repository
• the named worktree does not exist
• the worktree has local modifications and removal is refusing to continue

Remember:

• Grok Code creates worktrees under .grok/worktrees/
• each one gets a worktree- branch

MCP Looks Broken

Start with:

• grok mcp list
• grok mcp remote list
• /mcp

The most common confusion is scope:

• global config lives in ~/.grok/config.toml
• project config lives in .grok/config.toml

If a server is missing, make sure you added it to the scope you expected.

Exa Is Configured But Search Still Looks Missing

What to check:

• did /enable_exa finish successfully?
• did you restart Grok Code afterward?
• does /mcp show the exa server as available?

Grok Code saves the Exa config first, then the current session usually needs a restart for full activation.

Docs Cache Looks Stale Or Incomplete

What to know:

• docs cache entries expire after 7 days by default
• long entries can show up as shortened previews
• expired entries can disappear from normal lookup

Useful commands:

• /docs
• /docs get
• /docs clear
• /docs gc

Updates Or Rollbacks Feel Risky

What to know:

• grok update keeps local backups
• grok update --list-backups shows them
• grok update --rollback latest restores the newest backup

If an update fails, Grok Code usually prints the backup path you can use for rollback.

Uninstall Removes More Than The Binary

grok uninstall removes:

• the binary and backups
• config and runtime state under ~/.grok
• saved sessions and local data
• keyring entries
• shell PATH entries it knows how to clean up

Use it only when you really want a clean removal.

The Docs In This Repo Used To Point At Missing Pages

If you saw old broken links before this rebuild, that was a real mismatch in the repo, not user error.

Use the rebuilt user guide starting at Docs Home.