Troubleshooting

Common issues and how to fix them.

Diagnostics

Start by running the doctor command to check your installation:

jeff doctor
# Checks API key, Google auth, and system health

For more detailed output, use verbose mode:

jeff --verbose "test"

If you're having trouble with Google authentication, try re-authenticating:

jeff auth logout google
jeff auth google

Verify your Anthropic API key is set correctly:

jeff doctor
# Will show if API key is valid

# Re-run setup if needed:
jeff setup

jeff auth status

Error: API key not configured

Run jeff setup to configure your Anthropic API key.

Error: Google authentication required

Run jeff auth google to authenticate.

Error: Token expired

Re-authenticate with jeff auth google.

Error: Rate limit exceeded

Wait a few minutes and try again. Google and Anthropic have API rate limits.

Error: MCP server failed to start

Check the server command in .mcp.json. Try running it manually to debug.

If nothing else works, reset Jeff to a clean state:

# Remove all Jeff data
rm -rf ~/.jeff

# Set up again
jeff setup
jeff auth google

This removes credentials, config, conversation history, and cache. You'll need to reconfigure and re-authenticate.

Still stuck? Here's how to get help: