Skip to main content
This guide covers common issues you might encounter while using goose and provides step-by-step solutions.
Need help? Our Discord community is here to help! Consider generating a diagnostic report to help us understand your setup quickly.

​
Installation and Configuration

​
API Key Configuration Errors

Users may encounter errors when their LLM API tokens are incorrect, expired, or have insufficient credits: 
httpx.HTTPStatusError: Client error '404 Not Found' for url
'https://api.openai.com/v1/chat/completions'
Solution:
  1. Check Your API Credits: Log into your LLM provider’s dashboard and verify you have sufficient credits
  2. Verify API Key: Reconfigure your API key: 
    goose configure
  3. Test Connection: Start a new session to verify the configuration works
For detailed provider setup, see the Installation Guide.

​
Keychain/Keyring Errors

goose uses the system keyring (keychain on macOS) to store secrets securely. In environments where the keyring cannot be accessed, you may see: 
Error Failed to access secure storage (keyring): Platform secure storage failure:
DBus error: The name org.freedesktop.secrets was not provided by any .service files
Please check your system keychain and run 'goose configure' again.
Solution Options:

​
GitHub Copilot Provider Issues

OAuth Error with Lead/Worker Models: If you have lead/worker models configured, you might see: 
Failed to authenticate: Execution error: OAuth configuration not supported by this provider
Solution:
  1. Temporarily comment out lead/worker variables in ~/.config/goose/config.yaml: 
    # GOOSE_LEAD_MODEL: your-model
# GOOSE_WORKER_MODEL: your-model
  2. Run goose configure and complete GitHub Copilot OAuth
  3. Re-enable lead/worker settings if needed
Container/Keyring Issues: In Docker or headless environments: 
Failed to save token: Failed to access keyring: <error message>
Solution: 
GOOSE_DISABLE_KEYRING=1 goose configure

​
Provider and Model Issues

​
Using Ollama Provider

Ollama provides local LLMs. You must download models before use: Common Error: 
ExecutionError("error sending request for url (http://localhost:11434/v1/chat/completions)")
Solutions:
  1. Ensure Ollama is running: 
    # Start Ollama
ollama serve

# In another terminal, test the connection
curl http://localhost:11434/api/tags
  2. Download a compatible model: 
    # Download a model that supports tool calling
ollama pull qwen2.5
  3. DeepSeek limitations: DeepSeek models don’t support tool calling. All extensions must be disabled to use DeepSeek, which severely limits goose’s capabilities.
For more details, see Local LLMs.

​
Ollama on WSL (Windows)

If using Ollama with Windows Subsystem for Linux: 
Execution error: error sending request for url (http://localhost:11434/v1/chat/completions)
Solution:
  1. Find WSL’s gateway IP: 
    ip route show | grep -i default | awk '{ print $3 }'
  2. Use the IP instead of localhost: 
    # Example: http://172.24.80.1:11434
  3. Or enable WSL Mirrored Networking (Windows 11 22H2+): See WSL Networking Documentation

​
Rate Limit Errors (429)

goose may encounter rate limits when using LLM providers. Solution: Use a provider with built-in rate limiting or implement retry logic. See Handling LLM Rate Limits for detailed solutions.

​
Context Length Exceeded

This error occurs when input exceeds the model’s token limit. Solutions:
  1. Break down large tasks into smaller sessions
  2. Use .goosehints to provide concise context instead of large files
  3. Queue messages in goose Desktop to send them sequentially
  4. Switch to a model with larger context (e.g., Claude 3.5 Sonnet supports 200K tokens)
See Using Goosehints for more information.

​
Extension Issues

​
Extension Activation Failures

Extensions may fail to activate if package runners are not available: 
Failed to start extension `extension-name`: Could not run extension command
(`npx -y @modelcontextprotocol/server-github`): No such file or directory (os error 2)
Solutions:
  1. Install Node.js for npx-based extensions:
    • Download from nodejs.org
    • Verify installation: node -v && npx -v
  2. Install Python/uv for uvx-based extensions:
    • Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
    • Verify installation: uvx --version

​
Node.js Extensions on Windows

Error: 
Node.js installer script not found
Solution: goose expects Node.js at C:\Program Files\nodejs\. If installed elsewhere:
  1. Find your Node.js path: 
    where.exe node
  2. Create a symbolic link (as Administrator): 
    mklink /D "C:\Program Files\nodejs" "D:\Program Files\nodejs"
  3. Restart goose and try activating the extension again

​
Malicious Package Detected

goose blocks extensions that use malicious packages: 
Blocked malicious package: [email protected] (npm). OSV MAL advisories: MAL-2024-1234
Solutions:
  1. Find an alternative extension from trusted sources
  2. Verify the package is legitimate before reporting
  3. Report false positives by opening an issue
This security check uses the OSV database and only applies to locally-executed extensions using PyPI or NPM.

​
Hermit Errors

goose uses Hermit to ensure package runners are available: 
hermit:fatal - <error message>
Solution on macOS: 
sudo rm -rf ~/Library/Caches/hermit
Then restart goose and try again.

​
Network and Corporate Environment Issues

​
Corporate Proxy or Firewall

If behind a corporate proxy: 
error sending request for url (https://api.openai.com/...)
failed to connect to api.openai.com
Solution:
  1. Configure proxy environment variables: 
    export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal"
  2. Or use system proxy settings:
    • macOS: System Settings → Network → Details → Proxies
    • Windows: Settings → Network & Internet → Proxy
  3. Restart goose after configuration
  4. For authenticated proxies: 
    export HTTPS_PROXY="http://username:password@proxy:port"
See Network Configuration for more details.

​
Airgapped/Offline Environments

In restricted networks, extensions may fail to download dependencies: 
Failed to start extension: Could not run extension command
Workaround:
  1. Create alternatively-named package runners: 
    # For uvx (Python packages)
ln -s /usr/local/bin/uvx /usr/local/bin/runuv

# For npx (Node.js packages)
ln -s /usr/local/bin/npx /usr/local/bin/runnpx
  2. Update extension configurations: 
    extensions:
  example:
    cmd: runuv  # Instead of uvx
    args: [mcp-server-example]
  3. Why this works: goose only replaces known names (npx, uvx) with its shims. Custom names bypass this behavior.
In highly restricted environments, you may need to build a custom goose distribution with pre-configured shims. See Custom Distributions.

​
Runtime Issues

​
goose Stuck in a Loop

In rare cases, goose may enter a “doom spiral” during long sessions. Solution:
  1. Interrupt the current task: Hold Ctrl+C (CLI) or use the stop button (Desktop)
  2. End the session and start fresh: 
    goose session
  3. Break large tasks into smaller, more focused sessions

​
Long-Running Commands (CLI)

Development servers may cause goose to hang: 
npm run dev
python -m http.server
webpack serve
Solution: Customize shell behavior using GOOSE_TERMINAL. See Customizing Shell Behavior for details.

​
Permission Issues

​
macOS Permission Issues

If goose Desktop shows no window or tools fail to create files: Check permissions: 
ls -ld ~/.config
You should see drwx------ or similar with read/write for your user. Grant permissions: 
# Add read/write permissions
chmod u+rw ~/.config

# If directory doesn't exist
mkdir -p ~/.config
chmod u+rw ~/.config
System Settings (macOS):
  1. Go to System Settings → Privacy & Security → Files & Folders
  2. Grant goose access to necessary directories
Running goose with sudo may create root-owned files, causing further permission issues. Use this only for troubleshooting.

​
Data Management

​
Uninstall goose or Clear Data

goose stores data in platform-specific locations:
Data Locations:
  • Logs/Config: ~/.config/goose
  • Application Data: ~/Library/Application Support/Goose
  • Secrets: macOS Keychain (credential named “goose”)
Removal Steps:
  1. Stop all goose processes (check Activity Monitor)
  2. Open Keychain Access and delete the “goose” credential
  3. Remove data directories: 
    rm -rf ~/.config/goose
rm -rf ~/Library/Application\ Support/goose
  4. Delete the goose app from Applications folder

​
Session Management

​
goose Edits Files Unexpectedly

goose can and will edit files as part of its workflow. Best Practices:
  1. Use version control: Stage your personal edits before running goose
  2. Review changes: Leave goose edits unstaged until reviewed
  3. Separate commits: Create separate commits for goose’s edits so you can easily revert
  4. Use interrupts: Interrupt goose if it’s heading in the wrong direction

​
New Recipe Warning

The first time you run a recipe in goose Desktop, you’ll see a warning dialog. This is a security feature to prevent executing potentially harmful code. To proceed:
  1. Review the recipe’s title, description, and instructions
  2. Click Trust and Execute if you trust the source
  3. You won’t be prompted again for the same recipe unless it changes

​
Still Need Help?

If you’re still experiencing issues:
  1. Generate diagnostics: Create a diagnostic report with system info and logs
  2. Check the FAQ: Review Frequently Asked Questions
  3. Search Discord: Check our Discord community for similar issues
  4. File a bug report: Open an issue on GitHub with your diagnostic data
When asking for help, include:
  • Your OS and goose version
  • Provider and model being used
  • Steps to reproduce the issue
  • Relevant error messages or logs
  • A diagnostic report (if possible)

Build docs developers (and LLMs) love

Get started for freeTalk to us