Plans and help

Troubleshooting

Fixes for common Duscode problems, including missing keys, busy ports, a browser that won't open, slow WSL projects, git identity, pull requests, previews and budgets.

Start with:

bash

duscode doctor

It checks Node, git, the GitHub CLI, your keys, the port and folder permissions, and prints a fix: line for anything wrong.

Setup

"No provider keys" or "No AI provider key yet"

Open Settings → Models & keys, click Add key next to a provider and paste the key. It's checked and works at once, with no restart. See Add a provider key.

"No chat model available"

You have a key for a provider with no default models, such as Mistral or Groq. Add models for it in your config, or add an Anthropic or OpenAI key. See Add a model.

`duscode: command not found`

The installer didn't put duscode on your PATH in this shell. Open a new terminal. Under WSL, run the installer inside the Linux distribution, not in Windows.

Node is too old

Duscode needs Node 22 or newer. nvm install 22, then check with node -v.

Starting and opening

The browser didn't open

Open the address Duscode prints yourself: http://localhost:4317/code/. On WSL, install wslu (sudo apt install wslu) so Duscode can open your Windows browser.

"Port 4317 is busy; using 4318"

Another program has port 4317, so Duscode took the next free one. Use the address it prints. To choose a port, run duscode --port 4400.

"Port N is in use by another program"

You chose a port with --port and something else holds it. Pick another port.

The Duscode engine isn't running

The page lost the engine, and nothing answers on its port. Your sessions are saved, and the page reconnects by itself once Duscode is back.

Open a terminal.
Run duscode (or duscode restart, if you installed it as a service with duscode service install).
To see why it stopped, run duscode logs.

Duscode runs in the background and restarts its engine when it crashes, so this usually means it was stopped (duscode stop, a reboot) rather than crashed. To have it start at login, run duscode service install.

The Duscode engine stopped and is restarting

The engine crashed, and its supervisor is starting it again (after 1 s, 2 s, 5 s, 10 s, then every 30 s). Wait a moment: the page reconnects by itself. duscode status shows the last crash and its last log lines.

The Duscode engine keeps crashing, so it was stopped

It crashed 8 times in a row, each within a minute of starting, so the supervisor stopped trying.

Run duscode logs and read the last lines before each crash.
Fix the cause (a port another program holds, a broken config file in your settings folder).
Run duscode restart.

“Interrupted by a restart”

Duscode stopped while Dus was working on a task (a crash, duscode stop, a reboot). What it had done so far is kept. Press Continue in the session: Dus picks it up from where it stopped, with the whole conversation. Requests waiting in the queue run after it.

A service keeps crashing

A server Dus started (an API, a database) exited, was restarted a few times, then left stopped. Open Terminal → Services, press Log on it to read why, and ask Dus to fix it. Restart (or Start) runs it again with the same command.

WSL

Everything is slow

The project is probably on a Windows drive (/mnt/c/...). Move it into the Linux file system, for example ~/code/my-app. Installs, builds, git and file watching are many times faster there. Windows apps can still open it at \\wsl.localhost\Ubuntu\home\<you>\code.

Can I use Duscode from PowerShell?

No. Run Duscode inside WSL 2. Your Windows browser works with it as usual.

Tasks

"Stopped: this task reached its budget"

The task hit its spending limit ($2 by default). Send a new message to continue, or raise the limit.

"Not verified: checks fail"

Your project's checks still failed after Dus's fix attempts. Open the Tests tab to read the output, then click Ask Dus to fix them or fix it yourself. If a check is wrong for the project, set your own checks.

A command was refused

Some commands are never allowed, even with approval: sudo, force pushes, and other destructive ones. Run them yourself in your own terminal if you really need them.

The model can't read my image

You pinned a model that can't read images. Switch the model picker to Auto, or pin a model tagged Vision.

A provider error: 401, 403 or 404

These are errors you need to fix, so Duscode doesn't hide them with a fallback. A 401 means the key is wrong or revoked: use Replace next to it in Settings → Models & keys. A 403 means your account lacks access to the model. A 404 means the model name is unknown: check models in your config.

Git

"Git doesn't know who you are"

Set your name and email once:

bash

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Pull requests: the GitHub CLI isn't installed or signed in

Install it from cli.github.com, then run gh auth login once.

Push rejected

The remote branch has commits you don't have. Duscode never force-pushes. Bring them in first, for example by asking Dus to merge the remote branch, and resolve any conflicts.

Merge refused: "Not merged yet"

The list under Not merged yet says why. Common reasons: uncommitted changes in the session (commit them), or your main checkout isn't clean or isn't on the base branch (commit or switch there).

A session won't finish

Duscode refuses when work would be lost: uncommitted changes, or commits not merged or pushed. Commit and merge, push the branch, or ask Dus to.

Preview

See Live preview → When the preview fails.

Browser checks

"No headless Chromium found"

bash

npx playwright install chromium-headless-shell
npx playwright install-deps chromium     # Linux and WSL

Moving Duscode's data

Set DUSCODE_HOME=/some/dir to keep Duscode's own files somewhere else. Keys, recent projects and usage history move with it.

Still stuck?

Email support@duscode.com with the output of duscode doctor and what you were doing. Never send your API keys.