Skip to main content
← 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 .

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
StageExamplesOn the service
Checks before anything is createdThe app is not running; a state directory under a parent others can write to; a bad flagNothing
Creating the resourceQuota Exceeded (HTTP 403) on a device at its limitNothing
Starting the daemonNo systemd user manager; an HTTP proxy; restrict share daemon socket … invalid argumentThe resource, switched off
Waiting for servingqURL share did not become ready, for example beside a second --foreground daemonThe resource, switched off or stopped
A recipient’s accessResource Not Found on the recipient; the opener page instead of the appThe 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.

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 →

Book a pilot

Tell us what to hide. We’ll scope a pilot.

Enterprise starts with a paid pilot on one application, typically 60 to 90 days, credited in full toward year one if you convert within 60 days. After that, an annual package sized to what you protect, not per seat.