Docs Troubleshooting
Documentation

Troubleshooting

The shortlist of issues we see most often, with diagnostics and fixes you can apply yourself.

"Partial fix" warning

A row shows the Partial badge on Fix history.

What happened — the source HTML was patched (so your storefront links are healthy) but the Shopify URL redirect didn't save.

Common causes:

  • A duplicate redirect already exists with the same From URL — maybe you created one manually.
  • You've hit Shopify's per-store redirect cap (100,000).
  • Transient Admin API error during the fix.
  1. Click "Retry redirect"On the Fix history row. Retries the redirect installation in isolation.
  2. If duplicate, resolve itOpen Shopify admin → Online Store → Navigation → URL Redirects and decide which redirect should win.
  3. If at cap, clean up staleUse the Clean up stale action on the Redirects page to delete redirects that are no longer needed.

"AI quota exhausted" on Free

Free plan: 5 lifetime AI-generated suggestions. After that, Relink falls back to heuristic matches for the rest of your free use.

Fix — upgrade to Pro for unlimited AI. Until then, heuristic matches (exact handle, title match) still work, and you can still pick any live page manually from the drawer's autocomplete.

Scan stuck in queue

Scan has been "Queued" for more than a minute.

Common causes:

  • The background worker process is down or restarting (we monitor and auto-recover, but it can take a few minutes during deploys).
  • A previous scan didn't release its per-shop lock — usually self-heals within 60 seconds.
  • You hit MAX_QUEUE_DEPTH of 50 — extremely rare for a single store.
  1. Wait 60 secondsMost stuck states resolve themselves.
  2. Refresh the pageThe dashboard polls scan status; a refresh re-syncs.
  3. If still stuck after 5 minutesEmail laurencetuchin@gmail.com with your shop domain — we can clear the lock manually.

"Scope update required" prompt

You see a banner asking you to re-approve permissions.

What happened — Relink added a new API scope (often because Shopify deprecated an older one). Approve it and the banner will disappear. Approving is safe — every requested scope is documented in Settings → Permissions.

Scan finished, no broken links found

A clean scan is actually the goal — but if you're sure your store has broken links and Relink missed them:

  • Resources cap — on Free plan, only the first 100 resources are scanned. Upgrade to Pro for 2,500, or Business for unlimited.
  • External links — Relink only fixes internal store URLs. Links pointing to other domains are out of scope by design.
  • Theme code — broken links hard-coded in Liquid templates aren't read by Relink; only content (products, pages, blogs, collections, metafields) is scanned.

AI picked a weird replacement

The AI's choice is consistently wrong for one of your broken URLs.

  1. Open the drawerClick the row in the Open broken links table.
  2. Type the correct URLUse the autocomplete to search every live page.
  3. ApplyYour manual pick is logged as Manual and won't be overwritten by future scans.
Pattern we see

If you find yourself overriding the AI repeatedly on the same kind of URL (e.g. it keeps picking the wrong collection for archived products), email us a few examples. We use these to tune the prompt.

Redirect loop after applying a fix

Visiting a fixed URL sends the browser into a redirect chain.

Cause — usually a pre-existing manual Shopify redirect that now conflicts with Relink's. For example:

  • Old manual redirect: /products/a → /products/b
  • Relink-created: /products/b → /products/c
  • Result: /products/a → /products/b → /products/c (a chain — still works, but slow).

Open Shopify admin → URL Redirects and either delete the obsolete first hop, or update it to point straight at the final destination.

Undo didn't restore my link

The original fix was a Remove (the anchor tag was deleted). There's no stored destination to insert back, so Undo can only delete the Shopify redirect — it can't reconstruct the anchor. Re-add the link by editing the source content in Shopify admin.

Daily scan didn't fire

You set a daily scan hour but no scan ran.

  • UTC, not local — the hour is UTC. Check what UTC time corresponds to "today" for you.
  • Check Scan history — under /app/scans. If the run started but failed, it'll show with an error status.
  • Free plan — daily scheduled scans are Pro and Business only.

Still stuck?

Email laurencetuchin@gmail.com. Include your shop domain, the scan ID (visible on the Scan history row), and a description of what you saw vs what you expected. Average reply: under one business day.

Need a hand?

Email laurencetuchin@gmail.com — average reply under one business day.

Install Relink →