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 .
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.
| 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
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.
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; }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 jsonTo 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 jsonConfirm 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" )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.
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.