Skip to content

docs: add Linux and Windows paths to uninstall section #5371

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
EbonyLouis merged 1 commit into from
Oct 27, 2025
Merged

docs: add Linux and Windows paths to uninstall section #5371

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 88 additions & 41 deletions documentation/docs/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,20 @@ title: Troubleshooting

# Troubleshooting

Goose, like any system, may run into occasional issues. This guide provides solutions for common problems.
goose, like any system, may run into occasional issues. This guide provides solutions for common problems.

### Goose Edits Files
Goose can and will edit files as part of its workflow. To avoid losing personal changes, use version control to stage your personal edits. Leave Goose edits unstaged until reviewed. Consider separate commits for Goose's edits so you can easily revert them if needed.
### goose Edits Files
goose can and will edit files as part of its workflow. To avoid losing personal changes, use version control to stage your personal edits. Leave goose edits unstaged until reviewed. Consider separate commits for goose's edits so you can easily revert them if needed.

---

### Interrupting Goose
If Goose is heading in the wrong direction or gets stuck, you can [interrupt it](/docs/guides/sessions/in-session-actions#interrupt-task) to correct its actions or provide additional information.
If goose is heading in the wrong direction or gets stuck, you can [interrupt it](/docs/guides/sessions/in-session-actions#interrupt-task) to correct its actions or provide additional information.

---

### Stuck in a Loop or Unresponsive
In rare cases, Goose may enter a "doom spiral" or become unresponsive during a long session. This is often resolved by ending the current session, and starting a new session.
In rare cases, goose may enter a "doom spiral" or become unresponsive during a long session. This is often resolved by ending the current session, and starting a new session.

1. Hold down `Ctrl+C` to cancel
2. Start a new session:
Expand All @@ -32,31 +32,31 @@ For particularly large or complex tasks, consider breaking them into smaller ses

### Preventing Long-Running Commands

If you use Goose CLI and work with web development projects, you may encounter commands that cause Goose to hang indefinitely. Commands like `npm run dev`, `python -m http.server`, or `webpack serve` start development servers that never exit on their own.
If you use goose CLI and work with web development projects, you may encounter commands that cause Goose to hang indefinitely. Commands like `npm run dev`, `python -m http.server`, or `webpack serve` start development servers that never exit on their own.

You can prevent these issues by customizing your shell to handle these commands differently when Goose runs them. See [Customizing Shell Behavior](/docs/guides/environment-variables#customizing-shell-behavior) for details on using the `GOOSE_TERMINAL` environment variable.
You can prevent these issues by customizing your shell to handle these commands differently when goose runs them. See [Customizing Shell Behavior](/docs/guides/environment-variables#customizing-shell-behavior) for details on using the `GOOSE_TERMINAL` environment variable.

---

### Context Length Exceeded Error

This error occurs when the input provided to Goose exceeds the maximum token limit of the LLM being used. To resolve this, try breaking down your input into smaller parts. You can also use [`.goosehints`][goosehints] as a way to provide goose with detailed context and use [message queues](/docs/guides/sessions/in-session-actions#queue-messages) in Goose Desktop.
This error occurs when the input provided to Goose exceeds the maximum token limit of the LLM being used. To resolve this, try breaking down your input into smaller parts. You can also use [`.goosehints`][goosehints] as a way to provide goose with detailed context and use [message queues](/docs/guides/sessions/in-session-actions#queue-messages) in goose Desktop.

---

### Using Ollama Provider

Ollama provides local LLMs, which means you must first [download Ollama and run a model](/docs/getting-started/providers#local-llms) before attempting to use this provider with Goose. If you do not have the model downloaded, you'll run into the following error:
Ollama provides local LLMs, which means you must first [download Ollama and run a model](/docs/getting-started/providers#local-llms) before attempting to use this provider with goose. If you do not have the model downloaded, you'll run into the following error:

> ExecutionError("error sending request for url (http://localhost:11434/v1/chat/completions)")


Another thing to note is that the DeepSeek models do not support tool calling, so all Goose [extensions must be disabled](/docs/getting-started/using-extensions#enablingdisabling-extensions) to use one of these models. Unfortunately, without the use of tools, there is not much Goose will be able to do autonomously if using DeepSeek. However, Ollama's other models such as `qwen2.5` do support tool calling and can be used with Goose extensions.
Another thing to note is that the DeepSeek models do not support tool calling, so all goose [extensions must be disabled](/docs/getting-started/using-extensions#enablingdisabling-extensions) to use one of these models. Unfortunately, without the use of tools, there is not much goose will be able to do autonomously if using DeepSeek. However, Ollama's other models such as `qwen2.5` do support tool calling and can be used with goose extensions.

---

### Handling Rate Limit Errors
Goose may encounter a `429 error` (rate limit exceeded) when interacting with LLM providers. The recommended solution is to use a provider that provides built-in rate limiting. See [Handling LLM Rate Limits][handling-rate-limits] for more info.
goose may encounter a `429 error` (rate limit exceeded) when interacting with LLM providers. The recommended solution is to use a provider that provides built-in rate limiting. See [Handling LLM Rate Limits][handling-rate-limits] for more info.

---

Expand Down Expand Up @@ -127,12 +127,12 @@ To resolve:

#### Container and Keyring Issues

If you're running Goose in Docker containers or Linux environments without keyring support, authentication may fail with keyring errors like:
If you're running goose in Docker containers or Linux environments without keyring support, authentication may fail with keyring errors like:
```
Failed to save token: Failed to access keyring: Platform secure storage failure: DBus error: Using X11 for dbus-daemon autolaunch was disabled at compile time
```

Goose tries to use the system keyring (which requires DBus and X11) to securely store your GitHub token, but these aren't available in containerized or headless environments.
goose tries to use the system keyring (which requires DBus and X11) to securely store your GitHub token, but these aren't available in containerized or headless environments.

To resolve:

Expand All @@ -148,37 +148,84 @@ See [Keychain/Keyring Errors](#keychainkeyring-errors) for more details on keyri

### New Recipe Warning

The first time you run a given recipe in Goose Desktop, you'll see a `New Recipe Warning` dialog that allows you to review the recipe's title, description, and instructions. If you trust the recipe, click `Trust and Execute` to continue. You won't be prompted again for the same recipe unless it changes.
The first time you run a given recipe in goose Desktop, you'll see a `New Recipe Warning` dialog that allows you to review the recipe's title, description, and instructions. If you trust the recipe, click `Trust and Execute` to continue. You won't be prompted again for the same recipe unless it changes.

This warning helps protect against inadvertently executing potentially harmful recipe code.

---
### Uninstall Goose or Remove Cached Data
### Uninstall goose or Remove Cached Data

You may need to uninstall Goose or clear existing data before re-installing. Goose stores data in a few places. Secrets, such as API keys, are stored exclusively in the system keychain.
You may need to uninstall goose or clear existing data before re-installing. goose stores data in different locations depending on your operating system. Secrets, such as API keys, are stored exclusively in the system keychain/keyring.

Logs and configuration data are stored in `~/.config/goose`. And the app stores a small amount of data in
`~/Library/Application Support/Goose`.
#### macOS

You can remove all of this data by following these steps.
**Data Locations**

* stop any copies of goose running (CLI or GUI)
* consider confirming you've stopped them all via the activity monitor
* open the keychain and delete the credential called "goose", which contains all secrets stored by goose
* `rm -rf ~/.config/goose`
- **Logs and Config**: `~/.config/goose`
- **Application Data**: `~/Library/Application Support/Goose`
- **Secrets**: macOS Keychain (credential named "goose").

If you are using Goose Desktop on macOS, you may also need to remove the app itself.
* `rm -rf ~/Library/Application Support/Goose`
* Delete the "Goose" app from your Applications folder
#### Removal Steps

After this cleanup, if you are looking to try out a fresh install of Goose, you can now start from the usual
install instructions.
1. Stop any copies of goose running (CLI or GUI)

- Consider confirming you've stopped them all via Activity Monitor

2. Open Keychain Access and delete the credential called "goose", which contains all secrets stored by goose
3. Remove data directories:

```
rm -rf ~/.config/goose
rm -rf ~/Library/Application\ Support/goose
```
4. Delete the "goose" app from your Applications folder (if using goose Desktop).

#### Linux
**Data Locations**

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

#### Removal Steps

- Stop any copies of goose running (CLI or GUI)
- Clear secrets from your system keyring (if applicable)
- Remove data directories:

```
rm -rf ~/.local/share/goose/
rm -rf ~/.local/state/goose/
rm -rf ~/.config/goose/
```
#### Windows

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

#### Removal Steps

1. Stop any copies of goose running (CLI or GUI)

- Check Task Manager to confirm all instances are closed

2. Open Windows Credential Manager and delete credentials related to "goose"
3. Remove data directories:
```
rmdir /s /q "%APPDATA%\Block\goose"
rmdir /s /q "%LOCALAPPDATA%\Block\goose"
```
4. Uninstall the goose Desktop app from Settings > Apps (if applicable)

> After this cleanup, if you are looking to try out a fresh install of goose, you can now start from the usual install instructions.
---

### Keychain/Keyring Errors

Goose tries to use the system keyring to store secrets. In environments where there is no keyring support, you may
goose tries to use the system keyring to store secrets. In environments where there is no keyring support, you may
see an error like:

```bash
Expand Down Expand Up @@ -241,7 +288,7 @@ An example is the GitHub extension whose command is `npx -y @modelcontextprotoco

### Node.js Extensions Not Activating on Windows

If you encounter the error `Node.js installer script not found` when trying to activate Node.js-based extensions on Windows, this is likely due to Goose not finding Node.js in the expected system path.
If you encounter the error `Node.js installer script not found` when trying to activate Node.js-based extensions on Windows, this is likely due to goose not finding Node.js in the expected system path.

#### Symptoms:
- Node.js is installed and working (verified with `node -v` and `npm -v`)
Expand All @@ -264,9 +311,9 @@ This issue typically occurs when Node.js is installed in a non-standard location
```
(Replace `D:\Program Files\nodejs` with your actual Node.js installation path)

3. **Restart Goose** and try activating the extension again.
3. **Restart goose** and try activating the extension again.

This creates a symbolic link that allows Goose to find Node.js in the expected location while keeping your actual installation intact.
This creates a symbolic link that allows goose to find Node.js in the expected location while keeping your actual installation intact.

---

Expand All @@ -291,7 +338,7 @@ As a best practice, only install extensions from trusted, official sources.

### macOS Permission Issues

If you encounter an issue where the Goose Desktop app shows no window on launch, it may be due to file and folder permissions. This typically happens because Goose needs read and write access to the `~/.config` directory to create its log directory and file.
If you encounter an issue where the goose Desktop app shows no window on launch, it may be due to file and folder permissions. This typically happens because goose needs read and write access to the `~/.config` directory to create its log directory and file.
Similarly, if tools fail to create files or directories during use, it could be caused by the same permission issue.

#### How to Check and Fix Permissions:
Expand Down Expand Up @@ -323,24 +370,24 @@ Similarly, if tools fail to create files or directories during use, it could be
ls -ld ~/.config
```

If you still experience issues after fixing permissions, try launching Goose with superuser (admin) privileges:
If you still experience issues after fixing permissions, try launching goose with superuser (admin) privileges:
```sh
sudo /Applications/Goose.app/Contents/MacOS/Goose
```

:::note
Running Goose with sudo may create files owned by root, which could lead to further permission issues. Use this as a troubleshooting step rather than a permanent fix.
Running goose with sudo may create files owned by root, which could lead to further permission issues. Use this as a troubleshooting step rather than a permanent fix.
:::

#### Update permission in System Settings (macOs)
1. Go to `System Settings` -> `Privacy & Security` -> `Files & Folders`
2. Grant Goose access
2. Grant goose access

---

### Connection Error with Ollama Provider on WSL

If you encounter an error like this when setting up Ollama as the provider in Goose:
If you encounter an error like this when setting up Ollama as the provider in goose:
```
Execution error: error sending request for url (http://localhost:11434/v1/chat/completions)
```
Expand All @@ -353,7 +400,7 @@ This likely means that the local host address is not accessible from WSL.
```
ip route show | grep -i default | awk '{ print $3 }'
```
2. Once you get the IP address, use it in your Goose configuration instead of localhost. For example:
2. Once you get the IP address, use it in your goose configuration instead of localhost. For example:
```
http://172.24.80.1:11434
```
Expand All @@ -373,7 +420,7 @@ If you're working in an airgapped, offline, or corporate-restricted environment,
- Error messages like: `Failed to start extension: Could not run extension command`

#### Solution:
Goose Desktop uses **"shims"** (packaged versions of `npx` and `uvx`) that automatically download runtime environments via Hermit. In restricted networks, these downloads fail.
goose Desktop uses **"shims"** (packaged versions of `npx` and `uvx`) that automatically download runtime environments via Hermit. In restricted networks, these downloads fail.

**Workaround - Use Custom Command Names:**

Expand All @@ -400,13 +447,13 @@ Goose Desktop uses **"shims"** (packaged versions of `npx` and `uvx`) that autom
```yaml
extensions:
example:
cmd: runuv # This bypasses Goose's shims
cmd: runuv # This bypasses goose's shims
args: [mcp-server-example]
```

3. **Why this works:** Goose only replaces known command names (`npx`, `uvx`, `jbang`, etc.) with its packaged shims. Custom names are passed through unchanged to your system's actual executables.

4. **Require more changes**: In a corporate proxy environment or airgapped environment where the above doesn't work, it is recommended that you customize and package up Goose desktop with shims/config that will work given the network constraints you have (for example, TLS certificate limitations, proxies, inability to download required content etc).
4. **Require more changes**: In a corporate proxy environment or airgapped environment where the above doesn't work, it is recommended that you customize and package up goose desktop with shims/config that will work given the network constraints you have (for example, TLS certificate limitations, proxies, inability to download required content etc).

---
### Need Further Help?
Expand Down