Troubleshooting

Etsy connection / sync

"Etsy connection failed" on connect — check the callback URL registered in your Etsy app exactly matches https://etsy.plexultra.com/api/etsy/callback, and that both the keystring and shared secret are saved in Settings. Error detail is shown in the toast.
403 "Shared secret is required" / "incorrect shared secret" — the x-api-key must be keystring:sharedsecret; make sure the shared secret is saved (Settings shows a masked value when set).
Ledger "time window … no more than 31 days" — handled (the sync chunks 30 days at a time); if you see it, the build is stale.
Unmatched items after sync — use Settings → Resolve Items to map each to a product (saved as alias) or create it; then re-sync.

Profit overstated / costs missing — products imported from the catalogue start at $0 cost. Products → Missing costs filter → set printing/material costs.
Two pages disagree — usually a stale cached bundle; hard-refresh (Cmd+Shift+R). Revenue is net of refunds everywhere; the revenue card shows "net of refunds".
Duplicate fees — the sync auto-dedupes ledger fees; for legacy CSV fees use Remove Old Fees once.

Workflow "waiting" forever — no runner matches runs-on, or the runner is offline. Check Settings → Actions → Runners is Idle/online and has the ubuntu-latest label; check docker compose logs forgejo-runner.
docker: command not found — job ran in a container without docker; ensure the workflow uses container: docker:cli.
Duplicate mount point: /var/run/docker.sock — remove any explicit socket mount from the workflow; act_runner mounts it automatically.
unauthorized: reqPackageAccess on push — the REGISTRY_TOKEN secret is missing or lacks write:package. Recreate the Forgejo token and secret.
Deploy can't pull image — docker login git.plexultra.com on the host, or make the package public in Forgejo.
Stale UI after deploy — hard-refresh; nginx serves index.html no-cache and hashed assets immutable, so a refresh picks up the new bundle.

Clear All Orders (Data Import) bulk-deletes orders only; products, expenses, and customers are untouched. Re-sync from Etsy to rebuild. Product cost mappings (aliases, listing IDs, costs) live on products and survive an order clear.