Skip to content

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.

Where to look first

  • 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.jsonl records every permission request and what happened to it.
  • On macOS, launchagent.out.log and launchagent.err.log in ~/Library/Application Support/dive-desktop hold the background server's output.

Starting Dive

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

Models and modes

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

Tools

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

Skills

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

External tools and MCP servers

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

Uploads

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

Still stuck?

Copy the DIAGNOSTICS report and open an issue describing what you did and what you expected.

Clone this wiki locally