What the recipient sees, and what it means
| What they see | What it means | What to do |
|---|---|---|
| “Access link invalid” | The link was opened once already, or its --ttl passed before anyone opened it | Run qurl share again and send the new link |
| “Resource not found” | The resource was deleted after the link was made | Publish the app again, then send a new link |
| The link opens, then the app errors or never loads | The link worked; the app or dev server is down, asleep, or refusing the hostname | qurl status <CRID> should say serving; check the app on this machine |
| It worked, then later requests fail | The session reached its --session-duration, 1 hour by default | Send a new link with a longer --session-duration |
| No invitation arrived, or the passkey step fails | An enrollment problem, not a used link | Check qurl access list_invitations; the recipient can choose Email me a link if the page offers it |
Fetching, previewing and opening are different
The secret part of a qURL link comes after the #. Browsers and HTTP clients never send that part to a server, so a plain fetch of the link, such as a chat app building a preview card, gets only the opening page and cannot use the link.
Opening the link is what uses it: a browser that loads the page and runs its scripts presents the secret and starts a session. A security scanner that opens links in a real browser can therefore use the one opening. Whether a particular mail or chat service does that depends on how it is set up, and an “Access link invalid” page alone does not show who opened the link.
One more case spends a link without a working visit: when the link sets a session duration, the first request to the app must arrive within 10 seconds of admission. A browser that stalls in between leaves the link consumed and grants no access. A fresh link fixes it.
Steps
Check four things before blaming a scanner: whether the link was opened, whether its opening window passed, whether your app is serving, and whether the recipient’s session simply ended. “Access link invalid” means used or expired: send a fresh link from qurl share. For people who come back, switch to an email invitation, which is never used up.
Identify the mode
A link from
qurl sharehas a # part (https://qurl.link/#…) and opens once. An email invitation is not used up: the invited person comes back with their passkey. An address https://qurl.link/<CRID> with no # part is not a link at all; for a private app it opens only for the people you allowed.Check that the app is serving
An app that is offline looks like a broken link to the recipient.
qurl statusshows the state you asked for and the state the service observes. If it is not serving, start the app and check it at its local address.qurl status <CRID>Check: The observed state is serving.
Check the link’s state without opening it
Never open the recipient’s link to test it: that spends its one opening. With an account and API key, the API lists each link of the resource with its status (active, consumed, expired or revoked) and use_count.
curl https://api.layerv.ai/v1/resources/<CRID>/qurls \ -H "Authorization: Bearer $QURL_API_KEY"Check the app with a link of your own
On the device that published the app,
qurl getmints a separate link the same wayqurl sharedoes and opens it in your browser, so the recipient’s link is never touched.qurl get <CRID>Send a fresh link the right way
Make a new link; the app does not need publishing again. Check that the expiry line says “single use”. Send it in a direct message, not a public channel: whoever opens it first uses it. Avoid email and apps that preview links, because a scanner that runs the page could use its one opening. Don’t open it yourself to check it, for the same reason.
qurl share <CRID> --ttl 4h --session-duration 2hFor people who come back, invite them instead
A one-time link suits one visit. For a reviewer or contractor who returns, publish the app invite-only and invite their email: only that address gets in, after verifying the mailbox and saving a passkey, and nothing is spent when they open it. The reviewer guide walks the commands.
Send the recipient instructions with the link
Paste this into the direct message with the new link.
Here's a private link to the app: <link> It opens once, in your browser. Please open it on the device you'll review on, and don't forward it or paste it into other tools first. If it says "Access link invalid", tell me and I'll send a new one; nothing is wrong on your side.
What the recipient sees
With a fresh link in a direct message, the recipient opens it once and lands in the app.
More
An invited recipient opens the emailed invitation, verifies their mailbox, saves a passkey and comes back with it.
Troubleshooting
| If you see | Do this |
|---|---|
| Every new link is spent before the recipient opens it | Something on the path opens links in a browser. Send the link in a direct message on another channel, or invite the recipient by email instead: an invitation is not spent by being opened. |
| qurl publish says the local app is not accepting TCP connections | Start the app first and check that curl works on the same address. qurl publish connects to localhost as 127.0.0.1, so if your app listens only on IPv6 (on macOS or Linux, lsof -iTCP -sTCP:LISTEN -nP shows [::1]), publish 'http://[::1]:PORT' instead, or start the dev server with --host 127.0.0.1 and publish that address. Neither requires listening on your LAN. Keep the quotes: zsh treats the brackets as a pattern. |
Show 5 more fixes
| If you see | Do this |
|---|---|
| The recipient sees “Access link invalid” | The link was already used or has expired. Run qurl share again and send the new link. |
| The recipient sees “Resource not found” | The resource was deleted after the link was made. Publish the app again, then run qurl share and send the new link. |
| publish rejects http://127.0.0.1 with “only HTTPS URLs are allowed”, asks you to log in, or prints no Access: line | Your qURL CLI is out of date. On macOS run brew update, then brew upgrade qurl; elsewhere install the latest release. After updating, qurl --version prints 3.4.1 or later, and every publish is private by default. |
| publish says this Linux session “can’t reach a systemd user manager” | You are in a container or sandbox without a user service manager. Run qurl publish with --foreground; sharing lasts as long as that process runs. Container and CI setup → |
| publish says “Quota Exceeded” with “protected resource limit reached”, or “Your qURL account has reached a plan limit” | You can see this without an account: a device with no account can keep up to 3 active resources, with links that last up to 24 hours. Run qurl list --status active, then qurl delete <CRID> for any you no longer need (it asks you to confirm; --yes skips that). qurl stop keeps the resource, so it does not free a slot. |
Frequently Asked Questions
Did an email scanner open my link?
Possibly, but the error page alone cannot tell you. A plain link preview cannot: the secret part of the link comes after the #, and browsers and HTTP clients never send that part to a server, so a preview bot that fetches the link gets only the opening page. A scanner that opens the link in a real browser and runs its scripts can use the one opening, and the reviewer then sees “Access link invalid”. Send the link in a direct message to the reviewer, never open it yourself, and if it was used up, run qurl share again: the app does not need to be published again.
Can I test the link before I send it?
Not that link: opening it uses it. Run qurl get <CRID> on the device that published the app instead. It mints a separate link and opens the app in your browser, and the recipient’s link stays unused.
Should I ask IT to turn off link scanning?
No. Keep your organization’s scanning on and change the delivery: send the link in a direct message, or invite the recipient by email so there is no single-use link to spend.
How long does an unopened link wait?
Until its --ttl: 24 hours at most without an account, and up to 30 days with one. The service may grant less than you ask, and the CLI says so on stderr.
Who else can reach my app while the link is open?
Opening the link starts a session for that browser, which lasts 1 hour by default. After a browser opens it, another browser on the same public IP cannot use its access. A script or agent that opens the link without a browser is admitted by its network address instead, which other devices on that public IP share until the session ends. A link admits whoever opens it: the API’s IP and country rules do not apply to the signed links qurl share issues. Keep your app’s own sign-in for anything sensitive.
Send a fresh link
Mint a new single-use link for the same app; nothing needs publishing again. Send it in a direct message.