Common problems
| What you see | Likely cause | Fix |
|---|---|---|
A dmn command says no engine is running |
Commands never start the engine themselves | Open the app, or run dmn start |
| An agent never asks DMN | It isn't connected, or it started before you connected it | dmn config verify, then dmn skill-init --apply or dmn mcp-init --apply, and restart the agent |
| Results miss a file you just changed | The index is still catching up | dmn index --watch waits until it's searchable |
| Search says "semantic (vector) search degraded" | DMN couldn't turn the question into a vector, so the results come from keywords and the symbol graph only. The rest of the line says why: no working embedding model, a busy GPU, or an index built with another model | dmn doctor. If Embedding model fails: dmn models fetch, then restart DMN. A busy GPU or a re-embed clears on its own |
An agent's terminal can't find dmn |
DMN's folder isn't on its PATH, or the terminal started before the install | Open a new terminal. If that doesn't help, dmn doctor says which folder to add |
| The app's window never opens | Windows is missing the WebView2 runtime the app draws with | Install it from Microsoft's WebView2 page. The command line works without it |
| Indexing a big project is slow | Without a GPU set up, DMN reads code on the CPU | On an NVIDIA card: Settings ▸ GPU acceleration, or dmn gpu install-cuda |
| Anything else | dmn doctor |
What dmn doctor says
Each line is a check, marked OK, WARN or FAIL. A FAIL makes dmn doctor exit with an error, so scripts can use it. These are the ones that need you:
| Check | What it means | What to do |
|---|---|---|
| Daemon: not running or unreachable | The engine isn't running | Open the app, or dmn start |
| Daemon: unresponsive | The engine is running but doesn't answer | dmn stop, then dmn start |
| Crash dumps: the daemon crashed | The engine crashed in the last hour and wrote a crash report | dmn debug crash shows it; send it with your report (see below) |
| Binaries (PATH): not on PATH | Agents can't run dmn |
Add the folder it names to your user PATH; the installer normally does this |
| Binaries (PATH): two installs | Agents get a different dmn from the one you're running |
Remove or reorder the one it calls stale |
| Binaries (PATH): dmn-mcp-bridge not found | Your agents' MCP entries start a program that isn't there | Reinstall DMN, then dmn mcp-init --check |
| Other dmn builds (PATH) | Another dmn on your PATH differs from this one |
Remove, rename or reorder the stale one |
| WebView2 runtime: not detected | The app can't draw its window | Install WebView2 (see above) |
| MCP config: no MCP config detected | No agent has DMN's MCP server | dmn mcp-init --apply |
| Hooks: duplicate briefing hooks | The briefing hook is set both for your user and for the project, so it runs twice | Remove one; dmn hook-init --remove previews what it would take out |
| Embedding model: stub embedder active, or failed to load | No embedding model is loaded, so search can't match code by meaning. A stub one returns noise | dmn models fetch, then restart DMN: it loads the model when it starts |
| Models (embedder): embedder missing | The model search uses isn't on disk | dmn models fetch, then restart DMN |
| Embedding model: stored vectors are incompatible | The index was built with another model | dmn index --force |
| Index (project): not indexed | This folder isn't a project yet | dmn index, or open the folder in the app |
| Index (project): files await embedding and none landed | Search by meaning stays incomplete: the embedder is slow (fell back to the CPU) or stalled. Embedding still on its way after indexing passes, with the files left | Check the GPU / Tier and Embedding model lines, then dmn logs --level warn. Restarting DMN re-queues files a stalled embedder dropped; if it never finishes, dmn index --force |
| Index integrity: vectors are orphaned | Part of a project's search-by-meaning data can't be reached, so search misses that code. A FAIL when it's most of the project | dmn index --force in that project |
| Index integrity: a project with no ledger keeps rows | A folder that was indexed and then deleted left search data behind. It takes space but changes no results | dmn projects marks folders that are gone; dmn index "<path>" --drop deletes one's index |
| Memory refs: dangling refs | A project note names a file or folder that isn't in this checkout: moved, deleted, or on a branch you haven't pulled | Pull, or fix the note: dmn memory read <note>, then dmn memory write or dmn memory delete |
| Proxy build: an older build | The proxy still runs the version from before an update | dmn proxy enable hands over to the new one, or restart DMN |
| Gemini CLI sign-in: a Google account | Gemini CLI stopped serving personal Google accounts on June 18, 2026, so its panes fail to sign in | Switch it to a Gemini API key, or use Antigravity CLI. A Code Assist Standard or Enterprise license still works |
Logs and versions
dmn logsshows the engine's log.dmn logs --level warnshows only problems, and-ffollows it.dmn whoamisays which engine you're talking to: its version, its folders and its process, and warns when a second one is running.dmn config showprints the settings in effect and where each came from.
Still stuck
In the app, Settings ▸ About DMN ▸ Send feedback sends us a message straight from DMN. It shows you everything it will send first, and adds your system details only if you switch on Include system details.
Or write to support@getdmn.com with what you ran, what you saw and the output of dmn doctor. Read it first: it shows folder paths on your machine.