Grok Build launched on May 14, 2026, and the early adopter wave has surfaced a predictable set of errors. Most of them are configuration issues, not bugs. Here are the five most common problems and how to fix each one.

If you’re still setting up, start with the complete guide or the getting started walkthrough.

Error 1: Authentication Failed

The most common error you’ll see on first run:

Error: Authentication failed. Invalid or expired API key.
Run `grok auth` to re-authenticate.

Causes

• You installed Grok Build but never ran the auth flow
• Your SuperGrok subscription lapsed
• You’re using an API key that was rotated or revoked
• Environment variable XAI_API_KEY is set to an old value

Fix

# Re-run the auth flow
grok auth

# Or set your API key directly
export XAI_API_KEY="xai-your-key-here"

# Verify it works
grok ask "hello"

If you’re using OpenRouter instead of the xAI API directly:

export OPENROUTER_API_KEY="sk-or-your-key"

Then set the provider in your config file (~/.grok/config.json):

{
  "provider": "openrouter"
}

Check that your key is valid:

curl -s https://api.x.ai/v1/models \
  -H "Authorization: Bearer $XAI_API_KEY" | head -20

If you get a 401, generate a new key at console.x.ai.

Error 2: Permission Denied on File Operations

Error: Permission denied. Cannot write to /path/to/file.
Grok Build requires write access to the working directory.

Causes

• Running Grok Build in a directory you don’t own
• File system permissions are too restrictive
• macOS sandbox restrictions (if installed via a restricted method)
• The .grok/ config directory can’t be created

Fix

# Check ownership of your project directory
ls -la .

# Fix ownership if needed
sudo chown -R $(whoami) .

# Make sure .grok directory can be created
mkdir -p .grok && ls -la .grok

# On macOS, grant full disk access if needed
# System Settings > Privacy & Security > Full Disk Access > Terminal

If you’re running in a Docker container or CI environment:

# Run as the correct user
grok -p "your prompt" --output-format streaming-json

# Make sure your API key is available
export XAI_API_KEY="xai-your-key-here"

Error 3: Model Not Found

Error: Model "grok-3-beta" not found. Available models: grok-3, grok-3-mini, grok-3-fast

Causes

• Using an outdated model name from documentation or blog posts
• Custom model routing is misconfigured
• Your subscription tier doesn’t include the requested model
• OpenRouter model ID doesn’t match xAI’s naming

Fix

# Check your config for the model setting
cat ~/.grok/config.json

# Reset to default model by editing the config
# Set "model": "grok-3" in ~/.grok/config.json

The model names changed between the beta and GA release. Update any scripts or config files:

Old name	Current name
grok-3-beta	grok-3
grok-3-mini-beta	grok-3-mini
grok-build-preview	grok-3

If you’re routing through OpenRouter, use the full model path in your config:

{
  "model": "xai/grok-3"
}

Error 4: Request Timeout

Error: Request timed out after 120s. The model did not respond in time.

Causes

• Large codebase analysis exceeding the default timeout
• Network connectivity issues
• The xAI API is under heavy load
• You’re sending too much context (approaching the 256K limit)

Fix

Increase the timeout by editing your config file (~/.grok/config.json):

{
  "timeout": 300
}

Check your context usage during a session with the /tokens slash command.

Reduce context by excluding large directories in a .grokignore file (if supported by your version):

echo "node_modules/" >> .grokignore
echo "dist/" >> .grokignore
echo ".git/" >> .grokignore

If timeouts happen consistently:

# Switch to a faster model for large operations (use /model in-session or edit config)
# Set "model": "grok-3-fast" in ~/.grok/config.json

# Or use plan mode to break the task into smaller steps
grok --mode plan -p "refactor the auth module"

For CI/headless environments, set a generous timeout:

grok -p "fix the failing tests" --timeout 600 --output-format streaming-json

Error 5: Rate Limit Exceeded

Error: Rate limit exceeded. You've made too many requests. Retry after 60s.

Causes

• SuperGrok plan has per-minute request limits
• API key usage exceeded your billing tier
• Multiple Grok Build sessions running simultaneously
• Subagents spawning too many parallel requests

Fix

# Check your current usage with the /cost slash command in-session

# Wait and retry (the error tells you how long)
sleep 60 && grok -p "continue"

# Limit parallel subagents by editing ~/.grok/config.json:
# { "max_parallel_agents": 2 }

If you’re hitting rate limits regularly:

• SuperGrok users ($99/mo): The plan includes generous limits, but running multiple sessions or heavy subagent workloads can exceed them. Space out large operations.
• API key users: Check your tier at console.x.ai. The $1/1M input token rate applies, but there are still requests-per-minute caps.
• OpenRouter users: Rate limits depend on your OpenRouter plan, not xAI’s limits.

To avoid rate limits in automation:

# Add delays between operations in scripts
grok -p "task 1" --output-format streaming-json
sleep 5
grok -p "task 2" --output-format streaming-json

Bonus: Quick Diagnostic Command

Run this to inspect your Grok Build setup:

grok inspect

This shows:

• Authentication status
• API connectivity
• Model availability
• Config validity

If grok inspect passes but you’re still having issues, try a clean reinstall:

# Remove existing installation
rm -rf ~/.grok

# Reinstall
curl -fsSL https://x.ai/cli/install.sh | bash

# Re-authenticate
grok auth

FAQ

Why does Grok Build keep asking me to authenticate?

Your token is likely expiring between sessions. The most reliable approach is to set XAI_API_KEY in your shell profile (.bashrc, .zshrc) so it persists across terminals:

echo 'export XAI_API_KEY="xai-your-key-here"' >> ~/.zshrc

Can I use Grok Build offline?

No. Grok Build requires an active internet connection to communicate with xAI’s API. There’s no local model option. If you need offline coding assistance, look at tools that support local models via Ollama.

Why is Grok Build slower than expected?

The 256K context window means Grok Build reads a lot of your codebase before responding. Use a .grokignore file (if supported by your version) to exclude irrelevant directories. Also check if you’re on grok-3 (slower, more capable) vs grok-3-fast (quicker responses, slightly less capable).

Does Grok Build work on Windows?

Yes, via WSL2. The install script targets Unix-like systems. On Windows, install WSL2 first, then run the install script inside your WSL terminal. Native Windows support is not available yet.

How do I report a bug to xAI?

Report issues on the xAI Discord or the xAI community forum. Include the output of grok inspect for faster triage.

Why do subagents fail when the main agent works fine?

Subagents inherit your auth but have their own rate limit budget. If you’re running many parallel subagents, they can collectively exceed your rate limit even if individual requests are small. Reduce max_parallel_agents in your config.