Repository navigation
Troubleshooting
DuckTapeKiller edited this page Sep 13, 2026
·
1 revision
Common problems, grouped by where they show up. Each answer links to the page with the details.
- Settings > MODES > DIAGNOSTICS. Environment, startup timings, the state of each mode and recent errors, with Copy and Refresh buttons. Paste it into a bug report.
- The Execution Trace under a reply lists every tool call and marks the ones that failed.
-
~/dive/security-events.jsonlrecords every permission request and what happened to it. -
On macOS,
launchagent.out.logandlaunchagent.err.login~/Library/Application Support/dive-desktophold the background server's output.
| Symptom | What to do |
|---|---|
| macOS says Dive is damaged or can't be opened | Run xattr -dr com.apple.quarantine /Applications/Dive.app, using the path where the app is. See Installing Dive
|
listen EADDRINUSE 127.0.0.1:8080 |
Another server already uses the port, often another Dive server. Stop it, or change SERVER PORT in Pi mode's settings |
| The window opens blank | The server didn't answer. On macOS, check launchagent.err.log
|
| Startup takes several seconds longer on a Mac | Dive couldn't find node on the PATH, so it runs the server inside the app after waiting for the background one. Installing Node.js lets it use the background server |
| Symptom | What to do |
|---|---|
| A mode's icon is missing | Settings > MODES > ENABLED MODES |
| No models in llama.cpp mode | Load one from Settings > MAIN, or download one in the MODELS tab. See llama.cpp mode |
| "llama-server binary not found. Install it (brew install llama.cpp) or set its path in the llama.cpp settings." | Install llama.cpp, or set LLAMA-SERVER BINARY on the MODELS tab |
| "Port 8130 is already in use by another llama-server (not managed by this Dive instance)." | Stop the other server, or change SERVER PORT on the MODELS tab |
| A model fails with "System message must be at the beginning" | Tick MERGE SYSTEM PROMPTS in that model's advanced options |
| No models in LM Studio mode | Start LM Studio's local server and check LM STUDIO SERVER URL. See LM Studio mode |
| No models in Ollama mode | Check that Ollama runs and that OLLAMA SERVER URL is right, then press Refresh models. See Ollama mode |
| "Missing openai API key. Add it in Cloud settings or set OPENAI_API_KEY." | Save a key for that provider. See Cloud mode |
| Pi mode can't start pi, or lists no models | Check that pi runs in a terminal and has a model through /login, then send a first message. See Pi mode
|
| Symptom | What to do |
|---|---|
| The model never calls tools | Check that DATABASE is off, that the tool is on in Settings > TOOLS, and try switching NATIVE TOOL CALLING off or on |
Tool "..." is disabled in Tools settings. |
Switch the tool on for this mode |
| A permission request was refused without you answering | That is the timeout default action. See How the model uses tools |
| The thinking panel shows the tool budget was exhausted | Turn on Agent Mode, or raise AGENT TOOL BUDGET |
browse_act can't be switched on |
In 5.0.8 Settings has no switch for the browser tools. See Native tools |
"The browser engine is not installed. Run npx playwright install chromium in the Dive directory, then try again." |
Run that command in the Dive directory, as the message says |
| "Access to local or private network addresses is not allowed." | Web tools can't reach local addresses, by design. See Safety |
| "Only http and https URLs are allowed." | Give the tool an http or https address |
| A code tool can't reach a folder | Add the folder to ~/dive/allowed-dirs.json. See Native tools
|
| Symptom | What to do |
|---|---|
| A skill isn't listed | Check that the folder holds a file named exactly SKILL.md inside ~/dive/skills, ~/.agents/skills or an extra folder, then press RELOAD SKILLS |
| It's listed as "Not loaded" | The reason follows. See the rules in Create a skill |
| "There is no enabled skill named ..." | Check the name after /skill: and that the skill is switched on in this mode |
| The model never loads the skill by itself | Make its description say more clearly when to use it |
| The same skill appears twice across apps | Keep one copy. See Sharing with pi and Claude Code |
| Symptom | What to do |
|---|---|
| A plugin shows an error in Settings | Match the message in Create an external tool |
| A change to a plugin doesn't take effect | Press RELOAD EXTERNAL TOOLS. If you changed a file other than index.js, restart Dive's server |
| An MCP server's badge says FAILED | Read the error on the badge, and match it in Connect an MCP server |
| The MCP SERVERS section is missing | It isn't shown in Cloud or Pi mode |
| Symptom | What to do |
|---|---|
| "Unsupported file type" | Dive accepts .txt, .md, .js, .ts, .py, .html, .css, .json, .pdf, .jpg, .jpeg, .png, .gif and .webp
|
| A PDF upload fails with "pdftotext failed" | Install Poppler, for example brew install poppler on macOS |
| A large file won't upload | Uploads are capped at 50 MB |
Copy the DIAGNOSTICS report and open an issue describing what you did and what you expected.
These pages describe Dive 5.0.8. Source code: DuckTapeKiller/dive. Spotted a mistake? Open an issue.
Get started
Tools and skills
Build your own
Share and stay safe
How Dive works
Help