# Get unstuck: every qURL CLI message and its fix

> qURL CLI errors as printed, with the exit code, what a failed publish left behind, and the fix that worked. Reproduced with qURL CLI 3.7.1.

Source: https://layerv.ai/for-agents/qurl-cli-errors/

---

[← For agents](https://layerv.ai/for-agents/) 

# Get unstuck: every qURL CLI message and its fix

## What does this qURL CLI error mean, and what should I do?

Find the message below by its exact text. Each entry gives the command that printed it, the qURL™ CLI exit code, what the failure left on the service, and a tested fix. The rule that matters most: a publish that fails while starting its daemon has already created the resource, so publish again with the same state, or delete it before that state is thrown away.

**Reproduced with qURL CLI 3.6.1 and 3.7.1.** Each message was printed in a recorded run on Docker Desktop 4.55 for macOS (Linux arm64 containers) against the production service, and each fix was run until it worked. An entry says which releases its run covers. Verified November 5, 2026.

## Which failed publishes leave a resource behind

qurl publish checks the app, the state directory and its flags first, then creates the resource, then starts the daemon that serves it. A failure in the first part creates nothing: an app that is not running, an unsafe directory, or a bad flag. Neither does the device’s limit, which refuses the creation itself. A failure in the last part leaves the resource created and switched off: no systemd user manager, an HTTP proxy, a socket that cannot be restricted, or a second foreground daemon.

Fix the cause first, then publish the same address again with the same state: it finds that resource and keeps its CRID. To delete it instead, list what this identity published for that address, pick the CRID of this attempt, and delete that one after asking the user. Don’t delete every match: an identity that published the address before can own an older resource for it. The recovery page has the full procedure: it follows every page of the list, and confirms the delete.

## What to do with each exit code

Exit code 2 is a usage error and 8 is invalid input: fix the command and don’t run it unchanged. 3 is configuration: the state directory, its mode, or an environment variable. 5 means not found, deleted, or not open to this device: don’t retry in a loop. 6 is a permission or a plan limit. 7 is a conflict, such as a publish that asks for the other privacy.

Retry only 9, 10 and 11\. For 9, rate limited, wait minutes, not seconds. For 10, a server error, retry once later. For 11, unavailable, retry with backoff, except “qURL share daemon is already running”: retrying never helps there, so publish without --foreground while the first daemon runs. Exit code 12 means a link did not match its CRID: treat it as tampering and report it, never retry around it.

## Errors

__Errors, by message__
| Message                                                                                                                                                                                                                                                                                                            | Command                                       | Exit code |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | --------- |
| [Error: restrict share daemon socket: chmod /home/node/.local/state/qurl/connector-v2/daemon.sock: invalid argument](https://layerv.ai/for-agents/qurl-cli-errors/#restrict-share-daemon-socket)                                                                                                                   | qurl publish                                  | 1         |
| [Error: Other users can write to /home/node (mode 0777), so qURL can't safely keep its files under it.](https://layerv.ai/for-agents/qurl-cli-errors/#other-users-can-write)                                                                                                                                       | qurl whoami                                   | 3         |
| [Error: This Linux session can't reach a systemd user manager, so qURL can't keep sharing in the background.](https://layerv.ai/for-agents/qurl-cli-errors/#no-systemd-user-manager)                                                                                                                               | qurl publish                                  | 3         |
| [Error: qURL can't start local sharing while this process is configured to use an HTTP proxy.](https://layerv.ai/for-agents/qurl-cli-errors/#http-proxy)                                                                                                                                                           | qurl publish                                  | 3         |
| [Error: local app is not accepting TCP connections at 127.0.0.1:5999: start it, then try again: dial tcp 127.0.0.1:5999: connect: connection refused](https://layerv.ai/for-agents/qurl-cli-errors/#local-app-not-accepting)                                                                                       | qurl publish                                  | 1         |
| [Error: qURL share did not become ready (daemon running, resource diagnostic absent): qURL share <CRID> did not start serving within 30s (last state: desired=on, connection=connecting, serving\_epoch=1): context deadline exceeded](https://layerv.ai/for-agents/qurl-cli-errors/#share-daemon-already-running) | qurl publish --foreground                     | 11        |
| [Error: Quota Exceeded (HTTP 403)](https://layerv.ai/for-agents/qurl-cli-errors/#quota-exceeded)                                                                                                                                                                                                                   | qurl publish                                  | 6         |
| [Error: confirmation required: re-run with --yes (interactive confirmation needs a terminal)](https://layerv.ai/for-agents/qurl-cli-errors/#confirmation-required)                                                                                                                                                 | qurl delete                                   | 2         |
| [Error: Resource Revoked (HTTP 400)](https://layerv.ai/for-agents/qurl-cli-errors/#resource-revoked)                                                                                                                                                                                                               | qurl share                                    | 5         |
| [Error: Resource Not Found (HTTP 404)](https://layerv.ai/for-agents/qurl-cli-errors/#resource-not-found)                                                                                                                                                                                                           | qurl share                                    | 5         |
| [Error: this output is piped, and a browser is only opened on a terminal. Add --file <path> to download the file (--file - streams the raw bytes), or use \`qurl share\` to print an access link](https://layerv.ai/for-agents/qurl-cli-errors/#output-is-piped)                                                   | qurl get                                      | 2         |
| [Error: runtime supervision is "native", not "external"; enroll a dedicated empty state directory first with qurl login --anonymous --supervision external or qurl login --enrollment-token-file <path> --supervision external](https://layerv.ai/for-agents/qurl-cli-errors/#runtime-supervision-native)          | qurl --supervision external                   | 3         |
| [Error: --anonymous requires LAYERV\_KEY\_PROVIDER=local-key](https://layerv.ai/for-agents/qurl-cli-errors/#anonymous-requires-local-key)                                                                                                                                                                          | qurl login --anonymous --supervision external | 2         |

### What does “Error: restrict share daemon socket: chmod /home/node/.local/state/qurl/connector-v2/daemon.sock: invalid argument” mean?

```
Error: restrict share daemon socket: chmod /home/node/.local/state/qurl/connector-v2/daemon.sock: invalid argument
```

- `qurl publish`
- exit code `1`

**Left behind:** The resource was created and is switched off. It counts toward the device’s limit and keeps its CRID.

qurl keeps its control socket in its state directory, and that directory is on a folder shared from the host. Docker Desktop for macOS cannot set the mode of a Unix socket on a bind-mounted folder. --foreground does not avoid it. Set QURL\_CONNECTOR\_RUNTIME\_DIR to a directory inside the container for the publish and every later qurl command, then run the same publish again: it reuses the resource and its CRID. Or keep all of qurl’s state on a Docker volume with QURL\_CONNECTOR\_STATE\_DIR.

```
export QURL_CONNECTOR_RUNTIME_DIR=/tmp/qurl-run
qurl publish http://127.0.0.1:3000 --foreground
```

Reproduced with qURL CLI 3.6.1 and 3.7.1. In full: [Fix socket chmod invalid argument in Docker Desktop](https://layerv.ai/for-agents/fix-docker-desktop-socket-chmod-invalid-argument/).

### What does “Error: Other users can write to /home/node (mode 0777), so qURL can't safely keep its files under it.” mean?

```
Error: Other users can write to /home/node (mode 0777), so qURL can't safely keep its files under it.

  Hint: run `chmod go-w /home/node`, then retry. Or set QURL_CONNECTOR_STATE_DIR (or XDG_STATE_HOME) to a directory you own that other users can't write to.
```

- `qurl whoami`
- exit code `3`
- or any command that opens qurl’s state, such as qurl publish

**Left behind:** Nothing was created.

A directory on the way to qurl’s state is writable by other users, often after a chmod 777 in an image or setup script, and qurl will not keep a device credential under it. The CLI can also pass on the lower-level text “directory component <path> has unsafe mode <mode>” for the same rule. Run chmod go-w on the directory the message names. If it has to stay that way, set QURL\_CONNECTOR\_STATE\_DIR to a directory with no such parent. A directory inside the 0777 home is refused too; /tmp/qurl-state is accepted, because /tmp has the sticky bit.

```
chmod go-w /home/node
# or
export QURL_CONNECTOR_STATE_DIR=/tmp/qurl-state
```

Reproduced with qURL CLI 3.6.1 and 3.7.1.

### What does “Error: This Linux session can't reach a systemd user manager, so qURL can't keep sharing in the background.” mean?

```
Error: This Linux session can't reach a systemd user manager, so qURL can't keep sharing in the background.

  Hint: run `qurl publish <url> --foreground` to share from this terminal, or have your own process supervisor run `qurl daemon run --supervision external`.
```

- `qurl publish`
- exit code `3`

**Left behind:** The resource was created and is switched off. It counts toward the device’s limit and keeps its CRID.

A container or sandbox has no systemd user manager, so the background service that publish installs cannot start. Run the same publish with --foreground, as a background job that stays running. It finds the resource the failed attempt created and serves it under the same CRID.

```
nohup qurl publish http://127.0.0.1:3000 --foreground --quiet \
  > crid.txt 2> publish.log < /dev/null &
```

Reproduced with qURL CLI 3.7.1. In full: [Share an app from a container or CI](https://layerv.ai/guides/share-from-a-container-or-ci/).

### What does “Error: qURL can't start local sharing while this process is configured to use an HTTP proxy.” mean?

```
Error: qURL can't start local sharing while this process is configured to use an HTTP proxy.

  Hint: unset the lowercase http_proxy environment variable for this command, then retry.
```

- `qurl publish`
- exit code `3`

**Left behind:** The resource was created and is switched off. It counts toward the device’s limit and keeps its CRID.

The lowercase http\_proxy variable is set, and qurl does not start local sharing through a proxy. Run the publish without that variable. Publishing the same address again reuses the resource the failed attempt created.

```
env -u http_proxy qurl publish http://127.0.0.1:3000 --foreground
```

Reproduced with qURL CLI 3.7.1.

### What does “Error: local app is not accepting TCP connections at 127.0.0.1:5999: start it, then try again: dial tcp 127.0.0.1:5999: connect: connection refused” mean?

```
Error: local app is not accepting TCP connections at 127.0.0.1:5999: start it, then try again: dial tcp 127.0.0.1:5999: connect: connection refused
```

- `qurl publish`
- exit code `1`

**Left behind:** Nothing was created.

Nothing is listening on that address and port. Start the app, check it with curl on the same address, then publish. A dev server that listens only on IPv6 is published as http://\[::1\]:<port>.

```
curl -sS http://127.0.0.1:3000 >/dev/null && qurl publish http://127.0.0.1:3000
```

Reproduced with qURL CLI 3.7.1.

### What does “Error: qURL share did not become ready (daemon running, resource diagnostic absent): qURL share <CRID> did not start serving within 30s (last state: desired=on, connection=connecting, serving\_epoch=1): context deadline exceeded” mean?

```
Error: qURL share did not become ready (daemon running, resource diagnostic absent): qURL share <CRID> did not start serving within 30s (last state: desired=on, connection=connecting, serving_epoch=1): context deadline exceeded

  qURL share daemon is already running
```

- `qurl publish --foreground`
- exit code `11`
- while another foreground publish runs on the same state

**Left behind:** The resource was created and is stopped.

One state directory has one share daemon. A foreground publish starts it, so a second foreground publish cannot start another one, and gives up after about 30 seconds. While the first foreground publish runs, publish every other app without --foreground: the running daemon serves it within seconds. For the resource the failed attempt left stopped, run qurl start <CRID>. Every app stops answering when that first process exits.

```
qurl publish http://127.0.0.1:3001 -o json
# for the one left stopped:
qurl start <CRID>
```

Reproduced with qURL CLI 3.7.1.

### What does “Error: Quota Exceeded (HTTP 403)” mean?

```
Error: Quota Exceeded (HTTP 403)

  quota exceeded: protected resource limit reached (3/3) — revoke an unused resource or upgrade your plan (qURLs for resources you already have are not affected)
```

- `qurl publish`
- exit code `6`

**Left behind:** Nothing was created.

A device with no account can keep 3 resources at once, and a stopped one still counts. So does a resource that a failed publish left switched off. Link a free LayerV account with qurl account setup for more room. Or list the resources and, after asking the user, delete one that is no longer needed.

```
qurl account setup
# or, after asking the user:
qurl list --status active
qurl delete <CRID> --yes
```

Reproduced with qURL CLI 3.7.1.

### What does “Error: confirmation required: re-run with --yes (interactive confirmation needs a terminal)” mean?

```
Error: confirmation required: re-run with --yes (interactive confirmation needs a terminal)
```

- `qurl delete`
- exit code `2`

**Left behind:** Nothing was deleted.

delete asks for confirmation, and an agent’s shell is not a terminal. Confirm with the user that the resource should be deleted for good, then run it with --yes.

```
qurl delete <CRID> --yes
```

Reproduced with qURL CLI 3.7.1.

### What does “Error: Resource Revoked (HTTP 400)” mean?

```
Error: Resource Revoked (HTTP 400)

  Hint: this resource was deleted. Deleted resources can no longer be shared; publish the target again to get a new CRID.
```

- `qurl share`
- exit code `5`

The resource was deleted. The owner and every allowed device get this answer, and it is final. Publish the app again for a new CRID. In a cleanup script, this is the answer that confirms a delete: running qurl delete <CRID> --yes again still prints deleted: true.

Reproduced with qURL CLI 3.6.1 and 3.7.1. In full: [Recover a failed qURL publish safely](https://layerv.ai/for-agents/recover-failed-publish/).

### What does “Error: Resource Not Found (HTTP 404)” mean?

```
Error: Resource Not Found (HTTP 404)

  Hint: the CRID may be mistyped, the resource may have been removed, or this device may not be allowed to open it. If the resource is private, send the publisher this device's public key from `qurl whoami -o json` so they can allow it.
```

- `qurl share`
- exit code `5`
- or qurl get

The CRID is mistyped or removed, or the resource is private and this device is not on its list. Check the CRID. If it is right, ask the publisher to invite you by email: they run qurl access invite <CRID> --email <ADDRESS>, and you open the app from the invitation. Between two agents with no email, send the publisher this device’s device\_public\_key\_b64 from qurl whoami -o json; they allow it with qurl grants <CRID> --add <KEY>. Don’t retry in a loop.

```
# the publisher invites you:
qurl access invite <CRID> --email <ADDRESS>
# or, agent to agent, send the publisher your key:
qurl whoami -o json
```

Reproduced with qURL CLI 3.6.1 and 3.7.1. In full: [Private localhost access for AI agents](https://layerv.ai/for-agents/private-localhost-access-for-ai-agents/).

### What does “Error: this output is piped, and a browser is only opened on a terminal. Add --file <path> to download the file (--file - streams the raw bytes), or use \`qurl share\` to print an access link” mean?

```
Error: this output is piped, and a browser is only opened on a terminal. Add --file <path> to download the file (--file - streams the raw bytes), or use `qurl share` to print an access link
```

- `qurl get`
- exit code `2`

Without --file, qurl get opens a browser, and only does that on a terminal. An agent’s output is never one. Fetch the content with --file - (raw bytes to stdout) or --file <path>, or make a link with qurl share.

```
qurl get <CRID> --file -
```

Reproduced with qURL CLI 3.6.1 and 3.7.1.

### What does “Error: runtime supervision is "native", not "external"; enroll a dedicated empty state directory first with qurl login --anonymous --supervision external or qurl login --enrollment-token-file <path> --supervision external” mean?

```
Error: runtime supervision is "native", not "external"; enroll a dedicated empty state directory first with qurl login --anonymous --supervision external or qurl login --enrollment-token-file <path> --supervision external
```

- `qurl --supervision external`
- exit code `3`
- with any command, on a state directory made without it

The state directory was created for ordinary (native) use. --supervision external is for an app that runs qurl daemon run itself and seals its own state. Drop --supervision external. Ordinary use, in a container too, is native and needs no login. Never switch the mode of an existing state directory.

Reproduced with qURL CLI 3.6.1 and 3.7.1. In full: [Headless qURL: native or external supervision?](https://layerv.ai/for-agents/headless-native-vs-external-supervision/).

### What does “Error: --anonymous requires LAYERV\_KEY\_PROVIDER=local-key” mean?

```
Error: --anonymous requires LAYERV_KEY_PROVIDER=local-key
```

- `qurl login --anonymous --supervision external`
- exit code `2`

An externally supervised state directory must be sealed: LAYERV\_KEY\_PROVIDER=local-key, with the wrapping key on an inherited descriptor named by LAYERV\_LOCAL\_KEY\_FD. Unless you are building that supervisor, don’t log in at all: the first qurl publish creates the device identity, with no account.

Reproduced with qURL CLI 3.6.1 and 3.7.1. In full: [Headless qURL: native or external supervision?](https://layerv.ai/for-agents/headless-native-vs-external-supervision/).

## Notices that are not errors

### What does “Using a new device identity. Keep its local state, or run qurl account setup to enable recovery.” mean?

```
Using a new device identity. Keep its local state, or run qurl account setup to enable recovery.
```

- `qurl publish`
- notice, not an error
- or any first command on a new state directory, such as qurl whoami

There was no state yet, so qurl created a device identity. It owns every resource this device publishes. Nothing to fix. Keep the state directory for as long as you need its resources: in a container that is thrown away, delete them before it goes, because nothing else can.

Reproduced with qURL CLI 3.6.1 and 3.7.1.

### What does “This target was already published; showing the existing resource.” mean?

```
This target was already published; showing the existing resource.
```

- `qurl publish`
- notice, not an error

This device published that address before. With -o json, found\_existing is true. The resource keeps its CRID, its privacy and its approved people. Nothing to fix. Run qurl grants <CRID> -o json to see who can open it before you send the address.

Reproduced with qURL CLI 3.6.1 and 3.7.1.

## Frequently Asked Questions

Does a failed qurl publish leave anything behind? 

Sometimes. When publish fails while starting its daemon, the resource already exists and is switched off: the error names a systemd user manager, an HTTP proxy, the daemon socket, or a share that did not become ready. It counts toward the device’s limit. Publish again with the same state to keep its CRID, or delete it with qurl delete <CRID> --yes.

How do I confirm that qurl delete worked? 

Run qurl share <CRID>. It fails with “Resource Revoked (HTTP 400)” and exit code 5 once the resource is deleted. Running qurl delete <CRID> --yes a second time is no proof: it prints deleted: true again.

Why does qurl get fail in an agent’s shell? 

Without --file, qurl get opens a browser, and only on a terminal. Use qurl get <CRID> --file - to write the content to stdout, or --file <path> to save it.

How do I share two apps from one container? 

Start the first with qurl publish --foreground as a background job. While it runs, publish each other app without --foreground: the running daemon serves it. A second --foreground publish on the same state fails with exit code 11, “qURL share daemon is already running”.

## Related Resources

[Recover a failed qURL publish safely →](https://layerv.ai/for-agents/recover-failed-publish/) [qURL CLI JSON reference for automation →](https://layerv.ai/for-agents/qurl-cli-json-for-automation/) [Headless qURL: native or external supervision? →](https://layerv.ai/for-agents/headless-native-vs-external-supervision/) [Fix socket chmod invalid argument in Docker Desktop →](https://layerv.ai/for-agents/fix-docker-desktop-socket-chmod-invalid-argument/) [Guide: Share an app from a container or CI →](https://layerv.ai/guides/share-from-a-container-or-ci/) [Guide: Revoke access to an app you shared →](https://layerv.ai/guides/revoke-access-to-a-shared-app/) [The qURL skill →](https://layerv.ai/skills/qurl/SKILL.md) [qURL CLI →](https://layerv.ai/cli/)

## Give your agent the qURL skill

One file teaches a coding agent to publish an app privately, let people and other agents in, and recover when the CLI stops it. No account, no API key.

[Read the skill →](https://layerv.ai/skills/qurl/SKILL.md)



---

*This markdown version is auto-generated from [https://layerv.ai/for-agents/qurl-cli-errors/](https://layerv.ai/for-agents/qurl-cli-errors/) for AI agents. Curated agent resources: [llms.txt](https://layerv.ai/llms.txt). For the full interactive experience, visit the HTML version.*

