TroubleshootingCopy Anchor Link

English

SummaryCopy Anchor Link

This page helps you get unstuck when delorun cannot do what you asked, or when a phone cannot sign in to your studio. When delorun cannot do something, it prints a refusal: what it did or did not do, why, with an error code, and what you can do. Most refusals change nothing, so you can fix the cause and run the same command again.

Find yours by searching this page for the exact words or the code in the message. Every entry ends with a fix or says where to get help, and When nothing here fits says how to ask. You need nothing else first. Words such as home, profile and sandbox link to the glossary the first time they appear.

ContentsCopy Anchor Link

• Reading a refusal
• The home and its files
• Starting and stopping
• The studio port is busy
• Setup and the model key
• Installs and release checks
• Updates and rollback
• Repair the program and keep your data
• Last resort, by hand
• Protections and plugins
• Remote access and devices
• What a phone shows when it cannot sign in
• Archives, imports and the trash
• The workspace list
• When nothing here fits
• Next
• For the technically curious

Reading a refusalCopy Anchor Link

A refusal appears in your terminal in three parts: the first line says what happened, Why: names the error code and the path or value it concerns, and What you can do: lists the fixes in order. A refusal never shows a stack trace, and it hides keys and tokens the same way Delorun's logs do. The messages call the product "Delorun".

Delorun stopped before using /home/you/.delorun.
Why: HOME_MODE: /home/you/.delorun has mode 0755, which other users can reach; it must be 0700
What you can do:
  Fix it with: chmod 700 /home/you/.delorun

A fix that runs a delorun command repeats the --profile <name> you gave, so you can copy it as printed. After you fix the cause, run the command that refused again; you should see it finish without a refusal.

delorun exits with one of four codes, which scripts can rely on:

A command that fails without a code of its own starts with delorun <command>: and says what to do in the same sentence.

The home and its filesCopy Anchor Link

You should see the command run without a refusal once the fix is in. On Windows, Delorun does not check these permissions. Your Delorun home explains the home and its permissions.

A .env file in the folder you run delorun from, or in your Delorun home, may not set a name that starts with DELORUN_, because those names decide which home, profile and releases Delorun trusts. The refusal names the file. Remove the names from it, and set them in your shell instead if you need them.

Starting and stoppingCopy Anchor Link

• Delorun is already running for the profile default. delorun start found Delorun running and did nothing; this is not a failure. Open the studio with delorun open.
• HOME_UNRESPONSIVE. A process claims to be running this profile (it holds the profile's lock file) but did not answer within 2 seconds. Stop that process, or, if it is not delorun, remove the lock file the refusal names, then run delorun start again.
• Delorun is running for the profile … and uses the stores this command changes. Commands such as delorun trash, export and import change chat data that the running Delorun uses. Run delorun stop first, as the refusal says.
• another process … holds the home lock, or Delorun did not go ahead: another process uses the chat data. Another delorun command is changing the same data. Wait for it to finish, then run your command again.
• Delorun is being repaired; wait for it to finish. delorun repair is running and replaces the program, so no start can run until it ends. Wait for it to finish, then run your command again. If no repair is running (it was killed), the next start reports the leftover mark, removes it and goes on.
• the CLI profile default is not set up. Run delorun setup.
• Delorun found no folder for the default workspace. None of the folders Delorun tries for the default workspace can be used; the refusal lists each with the reason. Name a folder of your own in your profile's cordis.patch.yml, as the refusal shows, and start again.
• UNAUTHENTICATED. The running Delorun refused a command that did not carry the token of its current start, which usually means another Delorun is running for the profile. Run delorun status to see which one.
• STUDIO_UNAVAILABLE. delorun open could not get a sign-in link from the running Delorun. Run delorun status to see whether it runs and where the studio listens; if it does not run, start it with delorun start.
• Delorun started no new turn: its start check did not finish. Delorun's check of its release at start has not finished. delorun status and delorun logs show what the start is doing; start Delorun with delorun start, then send the message again.
• delorun start: the home process exited with code 1 before it was running; see its log: …. The background process stopped while starting. A busy studio port is the most common cause; see The studio port is busy.
• delorun start: the home process did not report running within … seconds; see its log: …. The background process is still starting or is stuck. Read the log the message names, or run delorun logs home, then run delorun doctor.

The studio port is busyCopy Anchor Link

The studio listens on one port on your own computer, 3080 unless your profile sets another. When another program already uses that port, the background process cannot start. You see:

delorun start: the home process exited with code 1 before it was running; see its log: <path>

To confirm the cause, run delorun doctor. It prints a failing port line that ends with "is in use by another process, so the studio cannot listen on it; stop that process, or choose another port with delorun setup profile". If your own Delorun already runs for the profile, the line instead says the port is in use by Delorun's studio and passes.

To fix it, either stop the other program, or run delorun setup profile (add --profile <name> for another profile) and answer a free port from 1024 to 65535 at "Port for the studio". Then run delorun start again. You should see "Delorun is running in the background for the profile default" with the studio's address, and delorun doctor shows port as passing.

Setup and the model keyCopy Anchor Link

• the key in DEEPSEEK_API_KEY was not accepted. Setup checks the key with the provider before it saves it, and the provider refused it. Check the key and run delorun setup again.
• DEEPSEEK_BASE_URL is not a URL. Fix or unset DEEPSEEK_BASE_URL; setup cannot check the key without a valid address.
• the setup run for default is unfinished and needs the model key. A setup started with --yes or --config stopped before it had a key. Run delorun setup in a terminal to finish it.
• … holds …, which setup no longer asks. A delorun setup --config document names an answer setup no longer has. Remove it from the document.
• … is not a setup record; remove it to set up again. The record of an unfinished setup is damaged. Remove the file it names and run delorun setup.

Installs and release checksCopy Anchor Link

The npm launcher and delorun update verify every release before they install it, and refuse one that does not verify; nothing is installed then. Install and first run explains what they check.

Two refusals come from the public release log itself. "Delorun could not reach the release log" means a network failure: check the connection and try again. "The release log answered with something Delorun does not accept" means the log's answer did not hold together: report it if it repeats. No setting turns the release-log check off (Release checks).

Updates and rollbackCopy Anchor Link

Updates explains the update itself. These are the refusals you are most likely to see; each one changes nothing unless it says otherwise.

delorun update --yes refuses a report that turns off or removes something, or holds an item Delorun cannot predict: run delorun update without --yes and decide each item. When an update is waiting for running chats to end, a new message gets "Delorun started no new turn: an update is waiting for running chats"; send it again once Delorun is back.

A refusal that starts "Delorun refused the change and left the profile as it was" protects something you added to your profile, so nothing was lost. Its code names what would have been lost:

Its fixes come from this list: do not take this update; keep the item and wait for a release that carries it; update the plugin; keep the plugin disabled; eject the plugin, which keeps its entries and settings in your profile; restore a profile history version with delorun recover restore <version>; go back with delorun recover rollback; or start in safe mode with delorun recover safe-mode. Run delorun recover status first to see where the profile stands. A refusal that starts "Delorun could not write the profile snapshot it takes before a change" (SNAPSHOT_FAILED) means nothing changed because the snapshot that makes the change undoable could not be written.

Repair the program and keep your dataCopy Anchor Link

If Delorun will not start because the installed program fails its check, or delorun update cannot run, replace the program and keep everything you made:

npx delorun@latest repair

Run it in a terminal. Delorun checks the release it installs the way an update does, asks Replace the installed program … with …? Your chats, settings and keys stay. [y/N], and puts the old program in runtimes.set-aside-<time>/ instead of deleting it. delorun recover status lists it and delorun recover discard runtimes.set-aside-<time> removes it once you are happy. Your chats, settings, keys, devices and trust records are not touched. Repair has no --yes, and it refuses while Delorun is running: stop it with delorun stop first.

Last resort, by handCopy Anchor Link

Use this only if npx delorun@latest repair cannot run. It needs no Delorun code.

1. Stop Delorun: delorun stop, or end the node processes that run @delorun/cli.
2. Back up your data. Copying the whole home with cp -a ~/.delorun ~/delorun-backup-$(date +%F) also copies runtimes/, which holds every installed release at about 1.5 GB each, so check that df -h ~ shows that much free space. Step 4 installs the programs again, so you can leave runtimes/ out: mkdir ~/delorun-backup-$(date +%F) && tar -C ~/.delorun --exclude=./runtimes -cf - . | tar -C ~/delorun-backup-$(date +%F) -xf -. delorun export saves single chats or workspaces only, so it is not a backup of settings and keys.
3. Move the program aside, not your data: mv ~/.delorun/runtimes ~/.delorun/runtimes.broken, and ~/.delorun/staging too if it exists.
4. Install again: npx delorun@latest. The program store is empty, so the launcher installs and checks the current release and starts it. Your chats, settings, keys and profiles are untouched.

Protections and pluginsCopy Anchor Link

• the profile default would boot without protections Delorun requires. A setting in your profile turns off a protection, such as the sandbox or one of Delorun's guards. The refusal lists each one with the file that sets it. Remove those settings, or start without your plugins with delorun recover safe-mode.
• the profile default could not load Delorun's bundle or plugins of Delorun's bundles did not start. Delorun stops rather than start without its guards and privacy settings, because the profile would otherwise run with DeepSeek Harness's own defaults. The refusal names each package, the cause and the fix.
• the landlock sandbox cannot deny the sockets in "<directory>". Your Linux system has no working bubblewrap, so commands would run under Landlock, which cannot hide the sockets of your login session, and Delorun refuses every sandboxed command while such a directory exists. If the refusal says to install bubblewrap, install the bubblewrap package and start again. If it says bubblewrap's check did not finish in time, your computer was busy when Delorun started: start it again. If it says bubblewrap is installed but could not create a sandbox, delorun doctor shows why on its sandbox line, or run bwrap --ro-bind / / true to see why; on Ubuntu the usual cause is its AppArmor restriction on user namespaces (kernel.apparmor_restrict_unprivileged_userns), which a profile for bwrap lifts for bwrap alone. Turning the restriction off for the whole system also works, but lowers its protection for every program.
• the sandbox row sets the runner itself or is configured with expressions. Delorun adds its home protection to the sandbox's settings at start, so those settings must leave the choice of sandbox to Delorun and use plain YAML values. Remove what the refusal names.
• delorun headless: … asks for full access in "<folder>", which you have not granted full access. A headless task asked to run outside the sandbox in a folder you have not put on full access, so it did not start. Run delorun workspace full-access <folder> on at your computer, or turn it on in the studio's Settings, Safety, Permissions, then run the task again. Or run the task without full access.
• full access for the workspace "<folder>" needs one consent for that workspace first. The model tried to switch a chat to full access in a workspace you have not allowed. A consent is a yes you give at your own computer. It stays on the safer preset. Allow it with the approval card's Allow for this chat, in Settings, Safety, Permissions, or with the delorun workspace full-access <folder> on command the message prints; see Full access.
• "Approve this at your computer". You tried to allow full access, an MCP server or another permission change from a phone. These answers are accepted only at the computer that runs Delorun. Do it there; see What an approved phone can and cannot do.
• This needs a quick unlock from your computer. You tried a sensitive action on a phone. Choose Unlock on the phone and approve the code at your computer (Unlock sensitive actions for a while).
• The network setting could not be read, so every workspace's commands have no network. The file that holds the network setting is damaged or other users can read it. Settings, Safety, Network names the problem. Repair or remove the file it names; the workspaces count as Off until you do.
• A command is refused because the workspace network is Allowlist or Off. Your sandbox cannot enforce those settings (only bubblewrap on Linux can), so Delorun refuses the command rather than run it with your network. Set the workspace back to Open in Settings, Safety, Network (The network setting).
• Delorun could not use the Docker engine. Docker did not answer, or refused the request with the HTTP status the refusal names. Start Docker and run the command again.

Letting bubblewrap run under Ubuntu's AppArmor restrictionCopy Anchor Link

From Ubuntu 23.10, AppArmor keeps a program from creating user namespaces unless a profile allows it, and kernel.apparmor_restrict_unprivileged_userns reads 1. bubblewrap needs them, so delorun doctor then fails its sandbox line and every sandboxed command is refused. A profile for bwrap alone allows them. Save this as /etc/apparmor.d/bwrap, with /usr/bin/bwrap replaced by the path command -v bwrap prints if it differs:

abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
}

Load it with sudo apparmor_parser -r /etc/apparmor.d/bwrap, check that bwrap --ro-bind / / true exits without an error, and restart Delorun. Any program can then create user namespaces through bwrap, which is what the restriction holds back, but every other program stays restricted.

Remote access and devicesCopy Anchor Link

These entries come from delorun reach and delorun devices at your computer. Reach the studio from your phone explains what remote access needs.

delorun reach on tailscale and delorun reach off print Tailscale's problems as delorun reach: <what happened> (<CODE>), and reach on adds "Remote access stays off." Nothing is turned on after such a refusal.

A refusal that starts "Delorun could not read or change what Tailscale serves for remote access" carries the same codes in its Why: line.

If delorun reach on tailscale says "the running Delorun did not make the address ready. Fix what the line above names, then run delorun reach on tailscale again", read the line above it, fix that, and run the command again. If it says "the running Delorun did not apply it" or "did not close its remote listener", restart Delorun with the command it prints.

These messages come from delorun devices:

• delorun devices: Delorun is not running. Start it with delorun start, then run delorun devices approve again. Approving needs the running Delorun. Run delorun start, then approve again. delorun devices elevate says the same with "so no device holds an unlock".
• delorun devices: No device asked for approval before the window closed. Run delorun devices approve again. Nobody asked within 5 minutes. Run the command again, then open your address on the phone and choose Ask for approval.
• That request is no longer waiting. The request ended on its own (it expired, or was cancelled on the phone). The command lists the waiting requests again; choose another, or ask again from the phone.
• That code is not the one the device shows. Try again. You may type it again. After the third wrong code the request is cancelled; ask again from the phone for a new code.
• Remote access is off for this profile, so a phone cannot reach this home yet. delorun devices approve waits, but no phone can reach you. Run delorun reach on tailscale.
• DEVICE_NOT_TRUSTED, "This home does not trust that device on this address. Ask for approval at the home's computer". The home refused a sign-in from a device it does not trust at this address: it was removed, or it was approved for another address. Ask for approval from the phone again, and approve it at your computer (Approve a device).

What a phone shows when it cannot sign inCopy Anchor Link

The sign-in page on the phone names the problem in its title.

When an unlock request fails, the phone says one of: "The code expired before your computer approved it." (choose Try again), "Your computer declined the request, or it was cancelled there." (ask again if you meant to unlock), "Your computer can't be reached right now. Check that Delorun is running there.", or "Too many requests are waiting at your computer. Answer them there, then try again." (open Settings → Devices at your computer, or run delorun devices elevate).

Archives, imports and the trashCopy Anchor Link

• "Delorun refused the archive and changed nothing." delorun import checks an archive before it writes anything; the code names the entry it refused.
• "Delorun stopped at the stock DeepSeek Harness home import." The import from ~/.dsh was refused, or a start found an interrupted import it could not remove; the code and detail say which. Switching from DeepSeek Harness explains the import.
• TRASH_ITEM_NOT_FOUND. The trash holds no item with that id; delorun trash list shows what it holds.

The workspace listCopy Anchor Link

Delorun keeps your workspaces in one file, storages/workspace.json in your home. A damaged file never stops Delorun from starting. Delorun starts with every workspace record it can read, moves the rest to a file named workspace.json.quarantined-<date and time>.json next to it, writes the cleaned list, and logs a warning that names the file and each record. delorun doctor lists the set-aside files. Delorun never deletes a set-aside file. If the whole file cannot be read, Delorun starts with no workspaces and sets the whole file aside. Your folders and chats are not touched.

Before every change to the list, Delorun keeps the previous good file as workspace.json.previous.

• Check it. delorun doctor has a workspaces line. It opens the file without changing it and prints pass for a readable list, warn when records would be set aside or earlier ones were, and fail for a file that cannot be read, naming the broken records and the set-aside files.
• Bring the previous list back. Stop Delorun (delorun stop), then run delorun recover workspaces. It shows what the current file and the previous copy hold, asks you to confirm (--yes answers for a script), moves the current file aside, and writes the previous copy in its place. It deletes nothing, and the copy stays. Run it at your own computer; it does not run while Delorun runs.
• Use the studio to rename. The agent renames a workspace with its rename_workspace tool after you allow it, so it never needs to edit the file by hand. If you edit workspace.json yourself, stop Delorun first.

When nothing here fitsCopy Anchor Link

Run delorun doctor. It checks Docker, the model key's format, your home, the studio's port, the release-log check, the last update check, your changes and your CLI profile's plugins, and prints one line for each. Run delorun logs home to read the running Delorun's recent records; Where Delorun keeps its logs explains each log.

A refusal that says "Report this" means Delorun found something it cannot explain. Report it with the refusal's text: a suspected vulnerability privately, as SECURITY.md describes, and anything else with the issue templates that CONTRIBUTING.md names, or to support@delorun.com.

NextCopy Anchor Link

• To check your setup after a fix, run delorun doctor, then delorun status.
• To understand what Delorun protects, read What Delorun protects.
• To read how logs help you, read Where Delorun keeps its logs.
• To set up remote access, read Reach the studio from your phone.

For the technically curiousCopy Anchor Link

Each code belongs to a contract that defines when it is raised: the delorun/docs/contracts/c01-home-layout.md for the home and installs, the delorun/docs/contracts/c19-home-process.md for starting, updates and devices, the delorun/docs/contracts/c07-reach-providers.md for the Tailscale codes, and the delorun/docs/contracts/c03-update-report.md for the update report and rollback. The codes that protect your profile are listed in the delorun/packages/profile-safety/README.md.