# Recover a failed qURL publish safely

> A failed qurl publish can still leave a resource on the service. How to tell, find it with the same identity, then resume or delete it and confirm.

Source: https://layerv.ai/for-agents/recover-failed-publish/

---

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

# Recover a failed qURL publish safely

## What should an agent do when qurl publish fails after creating a remote resource?

A qURL™ publish that fails while starting its daemon or waiting to serve has already created the resource and left it switched off. Keep the state directory and the error. With that same state, find the resource in qurl list by the address you published. Then either fix the cause and publish again, which reuses the same CRID, or delete that one CRID and confirm the deletion with qurl share.

**Checked against the qURL CLI source of 3.6.1 and 3.7.1.** The stages, the reuse of the CRID after a fix, and the revoked answer after a delete were reproduced with both releases in the runs behind the error reference. The procedure as a whole, and the effect of a delete on sessions already open, were not run for this page. Verified November 8, 2026.

## Which stage failed

qurl publish checks the app, the state directory and its flags, then creates the resource, then starts the daemon that serves it and waits for serving. Where it stopped decides what is on the service. Each publish error in the error reference says what it left.

A wrapper that reports only “Service exited before ready” hides the one thing you need: the stage. Get the CLI’s own stderr before deciding anything.

__What a failed qurl publish leaves on the service, by stage__
| Stage                             | Examples                                                                                 | On the service                               |
| --------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------- |
| Checks before anything is created | The app is not running; a state directory under a parent others can write to; a bad flag | Nothing                                      |
| Creating the resource             | Quota Exceeded (HTTP 403) on a device at its limit                                       | Nothing                                      |
| Starting the daemon               | No systemd user manager; an HTTP proxy; restrict share daemon socket … invalid argument  | The resource, switched off                   |
| Waiting for serving               | qURL share did not become ready, for example beside a second --foreground daemon         | The resource, switched off or stopped        |
| A recipient’s access              | Resource Not Found on the recipient; the opener page instead of the app                  | The resource, serving: not a publish failure |

## Recover it

1. ### Keep the state and the evidence  
Don’t remove the container, the volume or the state directory yet: it holds the only identity that can see or delete the resource. Write down the state directory (QURL\_CONNECTOR\_STATE\_DIR, or the default under $HOME/.local/state), QURL\_CONNECTOR\_RUNTIME\_DIR if it was set, the address you published, when the attempt started, any CRID it printed, the exit code, and stderr. Don’t run publish again yet: first find out what the attempt created.
2. ### Find the resource with the same identity  
Run qurl list with the same state and environment as the publish, follow every page, and match target\_url to the exact address. An identity that never published it sees nothing, so an empty list from the wrong state proves nothing. With a fresh state directory for the attempt, every match is the attempt’s. In a state that published this address before, a match can be older: compare created\_at with the attempt’s start time, or with a list saved before it. If that still leaves more than one candidate, stop and ask the user.  
```  
cursor="" listed=""
while page=$(qurl list --status active -o json ${cursor:+--cursor "$cursor"}); do
  more=$(printf '%s\n' "$page" | jq -r 'select((.resources | type) == "array") | .has_more | booleans') || break
  case "$more" in true|false) ;; *) break ;; esac
  printf '%s\n' "$page" | jq -r --arg t "$TARGET" \
    '.resources[] | select(.target_url == $t) | "\(.crid) created=\(.created_at // "-") desired=\(.desired_state // "-")"' || break
  if [ "$more" = false ]; then listed=complete; break; fi
  next=$(printf '%s\n' "$page" | jq -er '.next_cursor | strings | select(length > 0)') || break
  [ "$next" != "$cursor" ] || break
  cursor=$next
done
[ "$listed" = complete ] || { echo "inventory incomplete: delete nothing yet" >&2; false; }
```
3. ### To keep it: fix the cause and publish again  
Fix what the error named, for example by moving the socket with QURL\_CONNECTOR\_RUNTIME\_DIR, then run the same publish with the same state and the same address. It finds the resource, prints “This target was already published; showing the existing resource.”, and reports found\_existing true with the same CRID. A new state directory is a new identity: it creates a second resource, and the first stays and counts toward the limit. Moving only the runtime directory keeps the identity.  
```  
export QURL_CONNECTOR_RUNTIME_DIR=/tmp/qurl-run   # if the socket was the cause
qurl publish "$TARGET" -o json
```
4. ### To abandon it: delete that one CRID  
Ask the user first: delete is permanent. Delete only the CRID the previous step identified. Don’t run a loop that deletes everything published for an address: in an identity that owns older resources for the same address, it removes those too.  
```  
qurl delete "$CRID" --yes -o json
```
5. ### Confirm the deletion  
After a delete, qurl share on that CRID fails with exit code 5 and “Resource Revoked (HTTP 400)”. A timeout, a network error, another exit code, a stopped process or a closed local port is not a confirmation, and neither is “Resource Not Found (HTTP 404)”, which can mean the command ran as another identity. A refused share shows that no new links can be made. It does not by itself show that links handed out earlier, or sessions already open, stopped working; check those on their own if you report it.  
```  
(
err=$(mktemp) || exit 1
trap 'rm -f "$err"' EXIT
code=0
qurl share "$CRID" --ttl 1m >/dev/null 2>"$err" || code=$?
[ "$code" -eq 5 ] && grep -q 'Resource Revoked (HTTP 400)' "$err" && echo "delete confirmed"
)
```
6. ### Remove local state last  
Stopping the publish process or the container ends serving; it does not delete the resource. Remove the container and its state volume only once the delete is confirmed, or once the user decided to keep the resource and you no longer need the identity. If cleanup is still unresolved, keep the state and tell the user what is left.

## If you write a wrapper around qurl

A supervisor or broker that runs qurl for an agent should report the attempt’s state in words that match what happened: publish attempted, ownership not yet reconciled, owned resource known (with its CRID), serving, cleanup complete. These are suggestions for a wrapper’s own output; qurl prints none of them.

Keep blocking a second publish until the attempt is reconciled, but let the read-only qurl list run, and pass on a short excerpt of qurl’s stderr: its message names the stage. A broker that refuses the list and says only that the attempt already owns a resource leaves the agent with no way to find out.

## Frequently Asked Questions

Does a failed qurl publish always leave a resource? 

No. A failure in the checks before creation, or the device’s limit, creates nothing. A failure while starting the daemon or waiting for serving leaves the resource created and switched off. The error reference says which applies to each message.

Should I just run qurl publish again? 

Only after reading the error and fixing its cause, and only with the same state directory and the same address: then it reuses the resource and its CRID. With a new state directory it creates a second resource.

Why does qurl list show nothing after the failure? 

Either the failure came before the resource was created, or the list ran with another state directory, so another identity. Run it with the same QURL\_CONNECTOR\_STATE\_DIR, or the same home directory, as the publish, and follow every page.

Does “Resource Revoked” mean the links I already sent stopped working? 

It means the resource is deleted and no new link can be made for it. Whether a link handed out earlier, or a session already open, stops at once is a separate check: test it before you tell anyone it did.

Is stopping the publisher the same as deleting? 

No. Ending the --foreground process, qurl stop, or removing the container stops serving and keeps the resource and its CRID. Only qurl delete <CRID> --yes removes it, and only from the identity that owns it.

## Related Resources

[qURL CLI errors and exit codes →](https://layerv.ai/for-agents/qurl-cli-errors/) [qURL CLI JSON reference for automation →](https://layerv.ai/for-agents/qurl-cli-json-for-automation/) [An ngrok alternative for headless AI agents →](https://layerv.ai/for-agents/ngrok-alternative-for-headless-agents/) [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/) [The qURL skill →](https://layerv.ai/skills/qurl/SKILL.md)

## 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/recover-failed-publish/](https://layerv.ai/for-agents/recover-failed-publish/) for AI agents. Curated agent resources: [llms.txt](https://layerv.ai/llms.txt). For the full interactive experience, visit the HTML version.*

