# Troubleshooting

> What to do when DMN doesn't work: the engine isn't running, an agent never asks DMN, search misses a file, the app won't open, or dmn doctor warns about something.

Source: https://getdmn.com/docs/troubleshooting/

## 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 |
| 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](https://developer.microsoft.com/microsoft-edge/webview2/). 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` |
| 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 |
| 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: embedder missing, or failed to load | Search can't match code by meaning | `dmn models fetch` |
| 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 still awaiting embedding | Search by meaning is incomplete until they finish | Wait, or check the GPU; if it never finishes, `dmn index --force` |
| 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 |

## Logs and versions

- `dmn logs` shows the engine's log. `dmn logs --level warn` shows only problems, and `-f` follows it.
- `dmn whoami` says which engine you're talking to: its version, its folders and its process, and warns when a second one is running.
- `dmn config show` prints the settings in effect and where each came from.

## Still stuck

Write to [support@getdmn.com](mailto: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.