Common problems and fixes

What this is. A reference of the problems users hit most often with biorouter, each with the symptom, the cause where it is known, and the fix. Roughly twenty independent entries, grouped by the part of the system they affect. Status: Current, with one exception noted in place: the stack trace under API errors comes from an older Python agent and cannot be produced by Biorouter. Audience: end users

biorouter, like any system, may run into occasional issues. Use the contents below to jump to the entry that matches your symptom; entries are independent, so you do not need to read the page in order. If nothing here matches, generate a diagnostics bundle and open an issue — see Getting further help.

Note. The GitHub issues page is here to help. For the fastest support, generate a diagnostic report first — it helps maintainers understand your setup quickly.

Expected behaviour that can look like a problem
Sessions and long-running work
Providers and models
Secrets and the system keyring
Extensions and package runners
System permissions
Uninstalling biorouter or removing cached data
Getting further help

Expected behaviour that can look like a problem

Two behaviours are reported as bugs often enough to belong here, but both are intended.

biorouter edits files

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

New workflow warning

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

This warning helps protect against inadvertently executing potentially harmful workflow code. For how workflows are defined and shared, see the workflows guide.

Sessions and long-running work

Interrupting biorouter

If biorouter is heading in the wrong direction or gets stuck, you can interrupt it to correct its actions or provide additional information. The interrupt controls available inside a running session are listed under interactive session features.

Stuck in a loop or unresponsive

In rare cases, biorouter may enter a "doom spiral" or become unresponsive during a long chat. This is often resolved by ending the current chat and starting a new chat.

Hold down Ctrl+C to cancel.
Start a new chat:
```
biorouter session
```

Note. For particularly large or complex tasks, break them into smaller chats.

Preventing long-running commands

If you use biorouter CLI and work with web development projects, you may encounter commands that cause biorouter 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 biorouter runs them. See customizing shell behaviour for details on using the BIOROUTER_TERMINAL environment variable.

Context length exceeded error

This error occurs when the input provided to biorouter 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 .biorouterhints as a way to provide biorouter with detailed context, and use message queues in biorouter Desktop.

Providers and models

Using the Ollama provider

Ollama provides local LLMs, which means you must first install Ollama and pull a model before attempting to use this provider with biorouter. Two errors mean that step is missing (both measured with Ollama 0.40.2):

Request failed: error sending request for url (http://127.0.0.1:11434/api/chat) (failed to connect to 127.0.0.1:11434, check that the port is correct).

means no Ollama server answered: start Ollama, or check OLLAMA_HOST. Versions of biorouter before October 2026 named /v1/chat/completions in this message instead of /api/chat.

Request failed: Ollama model not found: qwen3.8:27b is not downloaded on this Ollama server. Run: ollama pull qwen3.8:27b  (Ollama said: model 'qwen3.8:27b' not found).

means the server is running but the model is not pulled; run the command it names.

Use one of the two recommended models, qwen3.8:27b (the default) or gemma4:31b. Many other Ollama models cannot call tools reliably: some write every tool call as JSON text, some return empty replies, and some (such as deepseek-r1:8b) never call a tool and invent its output. Tool-call protocols lists what 12 models did and which to avoid.

The model writes JSON instead of calling tools

If a local model answers with text such as {"name": "developer__shell", "arguments": {...}} instead of running the tool:

Update Ollama to 0.32.12 or later, which the recommended model qwen3.8:27b needs. Versions before 0.12.6 also cut a prompt that does not fit the context window instead of refusing it, and a model that sees only the end of biorouter's instructions writes invented tool calls as text. Biorouter now discards a reply to a prompt the server cut and says so, but it cannot make an old server stop cutting.
Read the error. A prompt that does not fit now stops the turn with a message naming the prompt size and the window. If it says biorouter's instructions and tools alone fill the window, set OLLAMA_NUM_CTX higher or turn off extensions you are not using.
Switch to a recommended model, qwen3.8:27b or gemma4:31b. Some models, such as qwen2.5-coder:7b, write every call as text through Ollama whatever the prompt. Biorouter runs such a call only when the whole reply is the call, every tool it names was offered, and its arguments are valid for that tool; a call that follows other text is shown as text.

Context window and settings explains how biorouter sizes the window and catches a cut prompt.

"Provider reported an error while streaming" with Llama Server

A chat on the Llama Server provider stops with this message, sometimes after part of the answer has appeared, and a later message in the same chat may work:

Ran into this error: Request failed: Provider reported an error while streaming. Contact your provider administrator.

Retrying will not help: this one returns the same way until its cause changes.

Cause. Biorouter 1.92.1 and earlier started llama-server with its default of four request slots sharing one context cache, 64k tokens on most computers. Every Biorouter request carries about 31k tokens of instructions and tool descriptions, so requests with different prompts running at the same time can fill that cache: two chats in different folders, a subagent or an app's agent beside a chat, or a scheduled job that runs during a chat. When they do not fit, llama-server stops every request it is running with Context size has been exceeded., and those versions reported that as the message above. Nothing about your setup has to be wrong, and retrying does help once the other requests finish.

Fix.

Update biorouter to 1.93.0 or later. Llama Server then runs one request at a time and queues the rest, so requests cannot collide in the cache.
If it still happens, the server is most likely one you started yourself: check whether LLAMACPP_EXTERNAL_HOST points at a llama-server running with its default settings, which share one cache between four slots. Start that server with --parallel 1, or give it a larger --ctx-size. Newer versions of biorouter name this failure ("ran out of room in its shared context cache") and retry it instead of giving up.

Connection error with the Ollama provider on WSL

If you encounter an error like this when setting up Ollama as the provider in biorouter:

Execution error: error sending request for url (http://localhost:11434/v1/chat/completions)

This likely means that the local host address is not accessible from WSL.

Check if the service is running:
```
curl http://localhost:11434/api/tags
```
If you receive a failed to connect error, it’s possible that WSL is using a different IP for localhost. In that case, run the following command to find the correct IP address for WSL:
```
ip route show | grep -i default | awk '{ print $3 }'
```
Once you get the IP address, use it in your biorouter configuration instead of localhost. For example:
```
http://172.24.80.1:11434
```

If you still encounter a failed to connect error, you can try using WSL's mirrored networking mode setting if you using Windows 11 22H2 or higher.

Handling rate limit errors

biorouter 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. For the retry and backoff settings biorouter exposes per provider, see provider retries.

API errors

You may run into an error like the one below when there are issues with your LLM API tokens, such as running out of credits or incorrect configuration:

Traceback (most recent call last):
  File "/Users/admin/.local/pipx/venvs/example-agent/lib/python3.13/site-packages/exchange/providers/utils.py",
line 30, in raise_for_status
    response.raise_for_status()
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/Users/admin/.local/pipx/venvs/example-agent/lib/python3.13/site-packages/httpx/_models.py",
line 829, in raise_for_status
    raise HTTPStatusError(message, request=request, response=self)
httpx.HTTPStatusError: Client error '404 Not Found' for url
'https://api.openai.com/v1/chat/completions'

...

Warning. This Python traceback is an old example from a Python agent installed with pipx, not output from Biorouter. Biorouter is a Rust program and cannot emit a pipx/httpx trace, so do not try to match your error against it. The surrounding advice still applies to the equivalent credential and credit errors in Biorouter.

This error typically occurs when LLM API credits are exhausted or your API key is invalid. To resolve this issue:

Check your API credits:
- Log into your LLM provider's dashboard.
- Verify that you have enough credits. If not, refill them.
Verify your API key:
- Run the following command to reconfigure your API key:
```
biorouter configure
```

For detailed steps on updating your LLM provider, refer to the installation guide.

GitHub Copilot provider configuration

If you encounter errors when configuring GitHub Copilot as your provider, try these workarounds for common scenarios.

OAuth error with lead/worker models

If the lead/worker model feature is configured in your environment, you might see the following error during GitHub Copilot setup. This feature conflicts with the OAuth flow to connect to the provider.

Failed to authenticate: Execution error: OAuth configuration not supported by this provider

To resolve:

Temporarily comment out or remove lead/worker model variables from the main config file (~/.config/biorouter/config.yaml):
```
# BIOROUTER_LEAD_MODEL: your-model
# BIOROUTER_WORKER_MODEL: your-model
```
Run biorouter configure again to set up GitHub Copilot.
Complete the OAuth authentication flow.
Re-enable your lead/worker model settings as needed.

Container and keyring issues

If you're running biorouter 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

biorouter 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, use the BIOROUTER_DISABLE_KEYRING environment variable to tell biorouter to store secrets in files instead. This example sets the variable only while executing the biorouter configure command:

BIOROUTER_DISABLE_KEYRING=1 biorouter configure

See Keychain and keyring errors for more details on keyring alternatives.

Secrets and the system keyring

Keychain and keyring errors

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

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 'biorouter configure' again.
If your system is unable to use the keyring, please try setting secret key(s) via environment variables.

In this case, you will need to set your provider specific environment variable(s), which can be found at Supported LLM providers.

You can set them either by doing:

export GOOGLE_API_KEY=$YOUR_KEY_HERE - for the duration of your session
in your ~/.bashrc or ~/.zshrc - (or equivalents) so it persists on new shell each new session

Then select No when biorouter configure asks whether to save the value in Biorouter's settings, so the key stays in your environment only.

$ biorouter configure

Welcome to biorouter! Let's get you set up with a provider.
  you can rerun this command later to update your configuration

┌   biorouter-configure
│
◇  Which model provider should we use?
│  Google Gemini
│
◇  GOOGLE_API_KEY is set via environment variable
│
◇  Save this value in Biorouter's settings?
│  No
│
◇  Enter a model from that provider:
│  gemini-2.0-flash-exp

You may also use the BIOROUTER_DISABLE_KEYRING environment variable, which disables the system keyring for secret storage. Set to any value (e.g., "1", "true", "yes"), to disable. The actual value doesn't matter, only whether the variable is set.

When the keyring is disabled, secrets are stored here:

macOS/Linux: ~/.config/biorouter/secrets.yaml
Windows: %APPDATA%\UCSF\biorouter\config\secrets.yaml

Extensions and package runners

Start with `biorouter doctor`

Before working through the fixes below by hand, run:

biorouter doctor

It prints one status line per prerequisite (Git, uv, Python 3, Node.js, AWS CLI, llama-server, the Rust toolchain) and says whether biorouter is on your PATH, so it names the missing piece directly. To hand a failing prerequisite to Biorouter itself, run biorouter doctor --fix <dependency>, for example biorouter doctor --fix uv, or leave the name off to take the first missing required one.

Hermit errors

If you see an issue installing an extension in the app that says "hermit:fatal", you may need to reset your hermit cache. biorouter uses a copy of hermit to ensure npx and uvx are consistently available. If you have already used an older version of hermit, you may need to clean up the cache — on Mac this cache is at

sudo rm -rf ~/Library/Caches/hermit

Package runners

Many of the external extensions require a package runner. For example, if you run into an error like this one:

Failed to start extension `{extension name}`: Could not run extension command (`{extension command}`): No such file or directory (os error 2)
Please check extension configuration for {extension name}.

... it signals that the extension may not have been installed and you need the package runner in order to do so.

An example is the GitHub extension whose command is npx -y @modelcontextprotocol/server-github. You'd need Node.js installed on your system to run this command, as it uses npx.

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 biorouter not finding Node.js in the expected system path.

Symptoms:

Node.js is installed and working (verified with node -v and npm -v).
Other extensions (like Python-based ones) work fine.
The error occurs specifically when activating Node.js extensions.

This issue typically occurs when Node.js is installed in a non-standard location. biorouter expects to find Node.js in C:\Program Files\nodejs\, but it may be installed elsewhere (e.g., D:\Program Files\nodejs\). To fix it:

Check your Node.js installation path:
```
where.exe node
```
If Node.js is not in C:\Program Files\nodejs\, create a symbolic link:
- Open PowerShell as Administrator.
- Create a symbolic link to redirect biorouter to your actual Node.js installation:
```
mklink /D "C:\Program Files\nodejs" "D:\Program Files\nodejs"
```
(Replace D:\Program Files\nodejs with your actual Node.js installation path.)
Restart biorouter and try activating the extension again.

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

Malicious package detected

If you see an error about a "blocked malicious package" when trying to use an extension, it means the extension was blocked because malware was detected in a package used by the extension. The error message will contain details about the package, for example:

Blocked malicious package: package-name@1.0.0 (npm). OSV MAL advisories: MAL-2024-1234

Steps to resolve:

Find an alternative: Look for similar extensions in the extensions directory or PulseMCP.
Optional verification: Verify the source of the blocked extension or the package name/publisher.
Report false positives: If you believe this is an error, please open an issue.

This security check only applies to locally-executed external extensions that use PyPI (uvx) or NPM (npx). The check uses real-time data from the OSV database; if the security service is unavailable, extensions will still install normally.

As a best practice, only install extensions from trusted, official sources.

Airgapped and offline environments

If you're working in an airgapped, offline, or corporate-restricted environment, you may encounter issues where MCP server extensions fail to activate or download their runtime dependencies.

Symptoms:

Extensions fail to activate with error messages about missing runtime environments.
Errors containing "hermit:fatal" or failed internet downloads.
Extensions work on personal machines but fail in corporate/restricted networks.
Error messages like: Failed to start extension: Could not run extension command.

biorouter Desktop uses "shims" (packaged versions of npx and uvx) that automatically download runtime environments via Hermit. In restricted networks, these downloads fail. The workaround is to use custom command names:

Create alternatively named versions of package runners on your system:

# 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

Update your MCP server configurations to use the custom names:

Instead of:

extensions:
  example:
    cmd: uvx
    args: [mcp-server-example]

Use:

extensions:
  example:
    cmd: runuv  # This bypasses biorouter's shims
    args: [mcp-server-example]

Why this works: biorouter 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.
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 biorouter 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).

System permissions

macOS permission issues

If you encounter an issue where the biorouter Desktop app shows no window on launch, it may be due to file and folder permissions. This typically happens because biorouter 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.

Checking permissions

Open Terminal.

Run the following command to check the current permissions for ~/.config:

ls -ld ~/.config

Example output:

drwx------  7 yourusername  staff  224 Jan 15 12:00 /Users/yourusername/.config

rwx indicates you have read (r), write (w), and execute (x) permissions for your user. If you do not see rwx for your user, follow the steps below.

Granting read and write permissions

To add the correct permissions, run the following commands:
```
chmod u+rw ~/.config
```
If the ~/.config directory does not exist, create it and then assign permissions:
```
mkdir -p ~/.config
chmod u+rw ~/.config
```
Verify the change:
```
ls -ld ~/.config
```

If you still experience issues after fixing permissions, try launching biorouter with superuser (admin) privileges:

sudo /Applications/Biorouter.app/Contents/MacOS/Biorouter

Note. Running biorouter 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.

Updating permissions in System Settings

Go to System Settings -> Privacy & Security -> Files & Folders.
Grant biorouter access.

Uninstalling biorouter or removing cached data

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

macOS

Data locations

Config: ~/.config/biorouter
Data and sessions: ~/.local/share/biorouter
Logs: ~/.local/state/biorouter
Application Data: ~/Library/Application Support/Biorouter
Secrets: macOS Keychain (credential named "biorouter").

biorouter info prints the first three for your own machine.

Removal steps

Stop any copies of biorouter running (CLI or GUI).
- Consider confirming you've stopped them all via Activity Monitor.
Open Keychain Access and delete the credential called "biorouter", which contains all secrets stored by biorouter.

Remove data directories:

rm -rf ~/.config/biorouter
rm -rf ~/.local/share/biorouter
rm -rf ~/.local/state/biorouter
rm -rf ~/Library/Application\ Support/Biorouter

Delete the "biorouter" app from your Applications folder (if using biorouter Desktop).

Linux

Data locations

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

Removal steps

Stop any copies of biorouter running (CLI or GUI).
Clear secrets from your system keyring (if applicable).

Remove data directories:

rm -rf ~/.local/share/biorouter/
rm -rf ~/.local/state/biorouter/
rm -rf ~/.config/biorouter/

Windows

Data locations

Configuration, data and logs: %APPDATA%\UCSF\biorouter\
Cache: %LOCALAPPDATA%\UCSF\biorouter\
Desktop app state: %APPDATA%\Biorouter\
Command line tool and helper programs: %LOCALAPPDATA%\Biorouter\
Secrets: Windows Credential Manager

Earlier releases kept the first two folders under a different author folder in the same two places. The desktop app moves them to the folders above when it starts, unless another Biorouter program is using the old folder at that moment; the move then waits for a later start.

Two folders after an update

If the old folder and the new one both exist, Biorouter uses the new one and leaves the old one exactly as it is. Anything saved in the old folder after the move (settings, chats, knowledge bases) does not appear in Biorouter. The desktop app says so when it starts, names the old folder and offers to open it; the daemon log says the same. This usually means an older copy of the biorouter command line tool ran after the update, or an earlier release of the app was opened.

To recover:

Quit Biorouter and every biorouter command that is running.
Update the command line tool: accept the Biorouter CLI update the desktop app offers, or run biorouter setup-path from the new release. Until then an older copy keeps writing to the old folder.
Decide which folder holds what you want to keep:
- The new one. Copy anything you need out of the old folder, then delete the old folder. Biorouter never deletes it on its own.
- The old one. Rename %APPDATA%\UCSF\biorouter to something else, for example biorouter-newer. The next time the desktop app starts, the old folder is the only one, so it is moved into place again and the paths saved inside it are updated. Copy anything you need out of the renamed folder afterwards.
Do not copy a whole folder over the other one. The chat database cannot be merged by copying, and a copied folder keeps paths that point at the folder it came from.

To stop the message without deciding, tick "Do not show this again for this folder". It is shown again if a different old folder appears.

If the old folder stays in use and never moves, something keeps it open: a biorouter command line session, an extension it started, or a program from the earlier release. Quit them, then start the desktop app again. The daemon log names the step that waited.

Removal steps

Stop any copies of biorouter running (CLI or GUI).
- Check Task Manager to confirm all instances are closed.
Open Windows Credential Manager and delete credentials related to "biorouter".

Remove data directories:

rmdir /s /q "%APPDATA%\UCSF\biorouter"
rmdir /s /q "%LOCALAPPDATA%\UCSF\biorouter"
rmdir /s /q "%APPDATA%\Biorouter"
rmdir /s /q "%LOCALAPPDATA%\Biorouter"

Uninstall the biorouter Desktop app from Settings > Apps (if applicable).

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

Getting further help

Still running into issues? Open an issue on GitHub where the biorouter team and community members are happy to assist.

Note. If you can share a diagnostic report along with your question, it helps maintainers understand your setup and provide more targeted solutions.

FilesExpand file tree

common-problems-and-fixes.md

Latest commit

History

common-problems-and-fixes.md

File metadata and controls

Common problems and fixes

Contents

Expected behaviour that can look like a problem

biorouter edits files

New workflow warning

Sessions and long-running work

Interrupting biorouter

Stuck in a loop or unresponsive

Preventing long-running commands

Context length exceeded error

Providers and models

Using the Ollama provider

The model writes JSON instead of calling tools

"Provider reported an error while streaming" with Llama Server

Connection error with the Ollama provider on WSL

Handling rate limit errors

API errors

GitHub Copilot provider configuration

OAuth error with lead/worker models

Container and keyring issues

Secrets and the system keyring

Keychain and keyring errors

Extensions and package runners

Start with biorouter doctor

Hermit errors

Package runners

Node.js extensions not activating on Windows

Malicious package detected

Airgapped and offline environments

System permissions

macOS permission issues

Checking permissions

Granting read and write permissions

Updating permissions in System Settings

Uninstalling biorouter or removing cached data

macOS

Data locations

Removal steps

Linux

Data locations

Removal steps

Windows

Data locations

Two folders after an update

Removal steps

Getting further help

Related documentation

Start with `biorouter doctor`