ThreadCloud SOPs

For the ThreadCloud team only

ThreadCloud SOPs

If something breaks

The on-call playbook. Match the symptom on the left to the fix on the right. If you’ve tried the fix and it didn’t work, don’t keep trying — email ThreadCloud Support at hello@threadcloud.io.

Quick triage

SymptomWhat to do
Page is blank / 500 errorRefresh once. Then restart the worker. Then email hello@threadcloud.io.
AI classification stuck or not progressingStop and restart — see below
Label printer not printingUse Shopify Admin fallback — fully supported
Supplier didn’t get the emailResend from PO tab
Shopify says “rate limit exceeded”Wait 60 seconds and try again. The worker retries automatically.
Image upload failedRe-upload the same image. If it fails twice, the image is too large — resize to under 4MB and retry.
”Missing access token” errorThis was a real bug — it’s been fixed. If you see it, refresh the page. If still broken after refresh, email hello@threadcloud.io.
Parse times out on a PDFTry Excel — see below
Apply Selected says “0 ready”Some rows are still NEEDS REVIEW. Filter to “Needs review”, fix each, then re-select.
Clean Catalog reports no safe fixesReview the source facts and the Legacy Enrichment queue. Ambiguous or incomplete rows are intentionally review-only; do not force an overwrite.
Inventory refresh fails on an untracked variantInventory snapshot refresh — the last good snapshot is retained.
Historical performance is unavailableHistorical ledger access — do not infer history from current stock.
Catalog rolled back wrongUndo via Legacy Enrichment
Order status won’t changeRefresh. If still stuck, check the supplier ack.
Wrong size receivedFix size on the receiving document. Do not unreceive it first — that hides the button.
Fixed a size but the document still shows the old oneCorrect and expected. A receiving document is a permanent record of that day, not live stock. Check the order’s Receive tab instead.

Worker stuck

If a background process (classification, enrich, push) appears frozen:

  1. Refresh the page. The worker auto-resumes from where it left off.
  2. If still stuck, click Stop on the workflow surface, wait 5 seconds, then click the run button again.
  3. If still stuck after 5 minutes, the worker may have hit an external API outage. Wait 15 minutes and retry once.
  4. If still broken: email hello@threadcloud.io with a screenshot.

Classification stuck

The progress bar isn’t moving and the ETA isn’t updating.

  1. Click Stop on the AI Classification step. Wait for it to confirm “Stopping…” → “Run Classification”.
  2. Click Run Classification again. The worker picks up only the pending rows.
  3. If the same row keeps failing, open the error drawer (“View errors” link at the top) — see what it says.
  4. If it’s an Anthropic API error, just keep retrying. The API recovers on its own.

Why this matters
The worker is designed to be safe to stop and restart at any point. It only claims rows in pending status, so re-running never duplicates work or wastes an AI call.

Printer fallback

The Dymo label printer isn’t responding, is out of labels, or jams repeatedly.

  1. Open Shopify Admin → Products.
  2. In the search bar, type tag:tc-order-247 (replace 247 with the order ID — find it in the URL of the order page in ThreadCloud, e.g. /app/orders/247/receiving).
  3. Select all rows that need labels. Click More actions → Print barcode labels.
  4. Choose your label size (Avery 5160 30-up sheet is the safest), pick the products, hit Print.

Why this works now
ThreadCloud writes the SKU into Shopify’s variant barcode field on every push. Shopify Admin reads from that field. So the SKU you’d see on a TC label is exactly what gets printed.

Heads up
The Shopify Admin label format isn’t identical to TC’s Dymo layout (no brand name, no colour name — just barcode + SKU + price). It’s a working fallback, not a like-for-like replacement.

Resend supplier

The supplier says they didn’t get the PO email, or you closed the window before saving.

  1. Open the order → click the PO tab.
  2. Scroll to the bottom and click Send to supplier again. The email re-sends with a fresh token.
  3. If the supplier already responded on the previous link, the new link supersedes it. Tell the supplier to ignore the old email.

Parse timeout

PDF parsing hangs or shows “Parse failed”.

  1. Try the same file again — once. Transient timeouts happen.
  2. If it fails twice, ask the supplier for an Excel version of the linesheet. Excel parses much faster and more reliably.
  3. If neither is available, open the order and click Add Style — manually add the rows. Slow but bulletproof.

Wrong rollback

You applied enrichment to a batch and the results are wrong.

  1. Open Settings → Legacy Enrichment.
  2. Scroll past the workflow to the Applied table at the bottom.
  3. Select the rows you want to undo. Click Rollback.
  4. Confirm. ThreadCloud restores the previous metafield values from the snapshot it took before applying.

Why this works
Every Apply step saves a snapshot of the existing values before overwriting. Rollback writes the snapshot back. This works for up to 90 days after the apply.

Inventory snapshot refresh

The Inventory Snapshot refresh reads Shopify inventory and rebuilds the snapshot. It does not write product metafields. Variants with inventory tracking disabled are excluded from physical totals, and a missing tracking signal for MTO, STOCK, or NOS fails closed so an unknown quantity is not reported as zero.

  1. Wait for the refresh to finish and check whether the page retained the last good snapshot.
  2. Fix the tracking or source issue, then run one refresh.
  3. If it fails again, stop retrying and record the product or variant id for support. Do not use the resulting total for a buying decision.

Historical ledger access

Historical sales requires the app’s Shopify read_all_orders grant. If the page asks for reauthorization, that is an app permission state, not a calculation to work around. Ask the owner to reauthorize the staging app, then retry once. Until the ledger is available, historical scorecards and MTO receipt-backed sell-through remain unavailable; current physical on-hand is not a substitute.

Stuck status

An order is stuck at “Sent to supplier” forever.

  1. Check if the supplier has responded — open the order → PO tab → look for the supplier ack timestamp.
  2. If they have responded, the page may need a refresh. Press Ctrl+Shift+R (hard refresh).
  3. If they haven’t, click Approve as-is on the PO tab — this skips the supplier loop and marks the order confirmed manually.

Big-picture failures

These are the rare ones. If you see one of these, email ThreadCloud Support immediately at hello@threadcloud.io — don’t try to fix them yourself.

SymptomWhat it means
Every page across the app is 500Production deploy is broken. Possibly a Fly.io outage or a bad merge to main. ThreadCloud Support handles this.
All Anthropic calls failing for 30+ minAnthropic API outage. Status: status.anthropic.com. Nothing to do except wait.
Shopify Admin won’t load at allShopify outage. Status: status.shopify.com. Wait.
Bank-side currency feed says the wrong rateThe multi-provider FX fallback should catch this. If somehow all three providers are wrong, set the FX manually on the order (Receiving tab) and email hello@threadcloud.io.
A push wrote products with bad dataDon’t panic. Pull them back: Shopify Admin → filter by tag:tc-order-{id} → bulk-delete. Then re-push from ThreadCloud after fixing the source.

What only the Owner should do

  • Approve a push of more than 200 products at once
  • Edit the AI prompts (Settings → AI & Models)
  • Change the metafield namespace or schema
  • Use the dev tools page (/app/settings/dev)

These are platform-level operations and only ThreadCloud Support should handle them:

  • Run direct database operations
  • Merge code to main (production)
  • Manual fly deploy to recover a broken production deploy

If your fingers are hovering over any of those, stop and ask.