> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/block/goose/llms.txt
> Use this file to discover all available pages before exploring further.

# Known Issues

> Solutions to common problems and known issues in goose

This guide covers common issues you might encounter while using goose and provides step-by-step solutions.

<Tip>
  **Need help?** Our [Discord community](https://discord.gg/goose-oss) is here to help! Consider generating a [diagnostic report](/troubleshooting/diagnostics) to help us understand your setup quickly.
</Tip>

## Installation and Configuration

### API Key Configuration Errors

Users may encounter errors when their LLM API tokens are incorrect, expired, or have insufficient credits:

```bash theme={null}
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:
   ```bash theme={null}
   goose configure
   ```
3. **Test Connection**: Start a new session to verify the configuration works

For detailed provider setup, see the [Installation Guide](/installation).

### 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:

```bash theme={null}
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:**

<Tabs>
  <Tab title="Environment Variables (Recommended)">
    Set your API key as an environment variable instead:

    ```bash theme={null}
    # For your current session
    export OPENAI_API_KEY="your-key-here"
    export ANTHROPIC_API_KEY="your-key-here"

    # Or add to ~/.bashrc or ~/.zshrc for persistence
    echo 'export OPENAI_API_KEY="your-key-here"' >> ~/.bashrc
    ```

    When running `goose configure`, select **No** when asked to save to keyring.

    See [Supported LLM Providers](/concepts/providers) for provider-specific environment variables.
  </Tab>

  <Tab title="Disable Keyring">
    Force file-based secret storage:

    ```bash theme={null}
    GOOSE_DISABLE_KEYRING=1 goose configure
    ```

    Secrets will be stored in:

    * macOS/Linux: `~/.config/goose/secrets.yaml`
    * Windows: `%APPDATA%\Block\goose\config\secrets.yaml`

    <Warning>
      File-based storage is less secure. Ensure appropriate file permissions are set.
    </Warning>
  </Tab>
</Tabs>

### GitHub Copilot Provider Issues

**OAuth Error with Lead/Worker Models:**

If you have lead/worker models configured, you might see:

```bash theme={null}
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`:
   ```yaml theme={null}
   # 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:

```bash theme={null}
Failed to save token: Failed to access keyring: <error message>
```

**Solution:**

```bash theme={null}
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:**

```bash theme={null}
ExecutionError("error sending request for url (http://localhost:11434/v1/chat/completions)")
```

**Solutions:**

1. **Ensure Ollama is running:**
   ```bash theme={null}
   # Start Ollama
   ollama serve

   # In another terminal, test the connection
   curl http://localhost:11434/api/tags
   ```

2. **Download a compatible model:**
   ```bash theme={null}
   # 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](/concepts/providers#local-llms).

### Ollama on WSL (Windows)

If using Ollama with Windows Subsystem for Linux:

```bash theme={null}
Execution error: error sending request for url (http://localhost:11434/v1/chat/completions)
```

**Solution:**

1. **Find WSL's gateway IP:**
   ```bash theme={null}
   ip route show | grep -i default | awk '{ print $3 }'
   ```

2. **Use the IP instead of localhost:**
   ```bash theme={null}
   # Example: http://172.24.80.1:11434
   ```

3. **Or enable WSL Mirrored Networking** (Windows 11 22H2+):
   See [WSL Networking Documentation](https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking)

### 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](/troubleshooting/known-issues) 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](/configuration) for more information.

## Extension Issues

### Extension Activation Failures

Extensions may fail to activate if package runners are not available:

```bash theme={null}
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](https://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:**

```bash theme={null}
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:**
   ```powershell theme={null}
   where.exe node
   ```

2. **Create a symbolic link** (as Administrator):
   ```powershell theme={null}
   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:

```bash theme={null}
Blocked malicious package: package-name@1.0.0 (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](https://github.com/block/goose/issues)

<Note>
  This security check uses the [OSV database](https://osv.dev/) and only applies to locally-executed extensions using PyPI or NPM.
</Note>

### Hermit Errors

goose uses Hermit to ensure package runners are available:

```bash theme={null}
hermit:fatal - <error message>
```

**Solution on macOS:**

```bash theme={null}
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:

```bash theme={null}
error sending request for url (https://api.openai.com/...)
failed to connect to api.openai.com
```

**Solution:**

1. **Configure proxy environment variables:**
   ```bash theme={null}
   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:**
   ```bash theme={null}
   export HTTPS_PROXY="http://username:password@proxy:port"
   ```

See [Network Configuration](/guides/environment-variables#network-configuration) for more details.

### Airgapped/Offline Environments

In restricted networks, extensions may fail to download dependencies:

```bash theme={null}
Failed to start extension: Could not run extension command
```

**Workaround:**

1. **Create alternatively-named package runners:**
   ```bash theme={null}
   # 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:**
   ```yaml theme={null}
   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.

<Warning>
  In highly restricted environments, you may need to build a custom goose distribution with pre-configured shims. See [Custom Distributions](/advanced/custom-distributions).
</Warning>

## 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:
   ```bash theme={null}
   goose session
   ```
3. **Break large tasks** into smaller, more focused sessions

### Long-Running Commands (CLI)

Development servers may cause goose to hang:

```bash theme={null}
npm run dev
python -m http.server
webpack serve
```

**Solution:**

Customize shell behavior using `GOOSE_TERMINAL`. See [Customizing Shell Behavior](/guides/environment-variables#customizing-shell-behavior) for details.

## Permission Issues

### macOS Permission Issues

If goose Desktop shows no window or tools fail to create files:

**Check permissions:**

```bash theme={null}
ls -ld ~/.config
```

You should see `drwx------` or similar with read/write for your user.

**Grant permissions:**

```bash theme={null}
# 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

<Warning>
  Running goose with `sudo` may create root-owned files, causing further permission issues. Use this only for troubleshooting.
</Warning>

## Data Management

### Uninstall goose or Clear Data

goose stores data in platform-specific locations:

<Tabs>
  <Tab title="macOS">
    **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:
       ```bash theme={null}
       rm -rf ~/.config/goose
       rm -rf ~/Library/Application\ Support/goose
       ```
    4. Delete the goose app from Applications folder
  </Tab>

  <Tab title="Linux">
    **Data Locations:**

    * Data/Sessions: `~/.local/share/goose/`
    * Logs: `~/.local/state/goose/`
    * Config: `~/.config/goose/`
    * Secrets: System keyring (if available)

    **Removal Steps:**

    1. Stop all goose processes
    2. Clear secrets from system keyring
    3. Remove data directories:
       ```bash theme={null}
       rm -rf ~/.local/share/goose/
       rm -rf ~/.local/state/goose/
       rm -rf ~/.config/goose/
       ```
  </Tab>

  <Tab title="Windows">
    **Data Locations:**

    * Configuration: `%APPDATA%\Block\goose\`
    * Local Data: `%LOCALAPPDATA%\Block\goose\`
    * Secrets: Windows Credential Manager

    **Removal Steps:**

    1. Stop all goose processes (check Task Manager)
    2. Open **Credential Manager** and delete goose-related credentials
    3. Remove data directories:
       ```powershell theme={null}
       rmdir /s /q "%APPDATA%\Block\goose"
       rmdir /s /q "%LOCALAPPDATA%\Block\goose"
       ```
    4. Uninstall goose Desktop from Settings → Apps
  </Tab>
</Tabs>

## 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](/api/cli/session) 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](/troubleshooting/diagnostics) with system info and logs
2. **Check the FAQ**: Review [Frequently Asked Questions](/troubleshooting/faq)
3. **Search Discord**: Check our [Discord community](https://discord.gg/goose-oss) for similar issues
4. **File a bug report**: [Open an issue on GitHub](https://github.com/block/goose/issues/new?template=bug_report.md) with your diagnostic data

<Tip>
  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)
</Tip>