> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/cli/help/troubleshooting/daemon-wont-start.md).

# The background process won't start

Fix the Devolutions CLI background process when it won't start or stops answering: check it, restart it, and review the --daemon settings that keep it off.

A command stops with `daemonUnavailable`, `daemonTimeout`, or `daemonIoError`, or hangs before it does anything. These errors come from the background process that `devo` starts to talk to your workspace. Their exit code is `3`.

Most of the time you never see this process: the first command that needs your workspace starts it, the following ones reuse it, and it stops by itself after 60 minutes without use. See [How Devolutions CLI works](/cli/guides/understand/how-it-works.md#the-background-process).

## Why it happens

* A setting tells `devo` not to start the process: `--daemon require`, `--daemon never`, or `--no-daemon-autostart`, or the matching environment variables.
* The process is running, but for another configuration folder.
* The process stopped answering, or a previous one didn't shut down cleanly.
* An environment variable that controls the process has a value it can't read.
* The local profile's configuration is protected and must be unlocked first.

## Fix it

{% stepper %}
{% step %}

### Check the process

```bash
devo daemon status
```

`Daemon running` with its process number means a background process is up. When several are registered, this is the preferred one, which can serve another configuration folder than yours: `devo doctor` then says so in a `Hint:` line. `Daemon not running` means none was found. For more detail, `devo daemon sessions --details` lists the registered background processes, with the configuration folder each one serves.
{% endstep %}

{% step %}

### Start or repair it

```bash
devo daemon ensure
```

It starts the process if none is running, repairs a registration that no longer answers, and shows the status. If the process still misbehaves, restart it:

```bash
devo daemon restart --wait
```

`--wait` waits for the old process to stop before starting the new one. To stop it without restarting, use `devo daemon stop --wait`. The next command that needs it starts it again.
{% endstep %}

{% step %}

### Check the settings that keep it off

<table><thead><tr><th width="330">MESSAGE</th><th>WHAT TO DO</th></tr></thead><tbody><tr><td>"The Devolutions CLI daemon is not running, and --daemon require (or DEVO_DAEMON_MODE=require) prevents starting one."</td><td><code>require</code> only uses a process that's already running. Run <code>devo daemon ensure</code> first, or switch back to <code>--daemon auto</code>.</td></tr><tr><td>"… --no-daemon-autostart (or DEVO_DAEMON_AUTOSTART) prevents starting one."</td><td>Remove <code>--no-daemon-autostart</code>, or unset <code>DEVO_DAEMON_AUTOSTART</code> (the values <code>0</code>, <code>false</code>, and <code>no</code> turn the automatic start off). Or run <code>devo daemon ensure</code> first.</td></tr><tr><td>"Daemon-backed commands are disabled by --daemon never."</td><td>The command needs the process. Use <code>--daemon auto</code> or <code>require</code>, and check that <code>DEVO_DAEMON_MODE</code> isn't set to <code>never</code>.</td></tr><tr><td>"Unsupported DEVO_DAEMON_MODE '&#x3C;value>'. Use auto, require, or never."</td><td>Fix or unset <code>DEVO_DAEMON_MODE</code>.</td></tr><tr><td>"DEVO_DAEMON_IDLE_TIMEOUT must be a duration like 30s, 15m, 1h, or 00:30:00."</td><td>Fix or unset <code>DEVO_DAEMON_IDLE_TIMEOUT</code>.</td></tr></tbody></table>

See [Global options](/cli/reference/global-options.md) and [Environment variables](/cli/reference/environment-variables.md).
{% endstep %}

{% step %}

### Check the configuration folder

Each configuration folder has its own background process, so two terminals that use different folders don't share one. If a message says "the running daemon serves another root", the process that's running is for another folder. In the default `--daemon auto` mode, `devo` starts one for your folder by itself. With `require` or `--no-daemon-autostart`, run `devo daemon ensure` from the terminal that needs it.

`devo config path` prints the configuration folder `devo` uses, without starting anything.
{% endstep %}

{% step %}

### Check the workspace runtime

When the process runs but commands on a local profile fail, check what it loaded:

```bash
devo runtime status
```

It shows whether the runtime is loaded, the profile folder and workspace in use, and the reason when something is blocked. After you change the profile outside Devolutions CLI, for example in Devolutions Remote Desktop Manager, reload it:

```bash
devo runtime reload
```

If the local profile's configuration is protected by an application password, unlock it for the running process. The password is read from an environment variable or a file:

```bash
devo config unlock --password-env <VARIABLE_NAME> --yes
```

{% endstep %}
{% endstepper %}

{% hint style="info" %}
To see when `devo` starts the process, add `--verbose` to a command: the notice `Starting Devolutions CLI daemon...` goes to the standard error stream, even with `--output json`.
{% endhint %}

## Still failing?

Run `devo doctor`: it checks the process without starting one, and its `Hint:` lines suggest what to do next. Then [collect diagnostics](/cli/help/troubleshooting/collect-diagnostics.md) and contact [Devolutions support](https://devolutions.net/support/).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.devolutions.net/cli/help/troubleshooting/daemon-wont-start.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.