Troubleshooting
Each subsection is symptom → cause → fix, for the situations admin users actually hit.
Signing in
| Symptom | Likely cause | Fix |
|---|---|---|
| Red banner “Invalid credentials” | Typo in email or password | Retype carefully; check caps lock. If unsure, use Forgot password? |
| Error mentions “multiple organizations” | Your email exists in more than one organization | Fill in the Organization ID field that appears and sign in again (Signing in) |
| “too many requests, slow down” | More than ~10 attempts in a minute from your network | Wait a minute, then try once, carefully |
| Reset link says “This reset link is invalid or has expired.” | Links expire after about an hour, and are single-use | Request a fresh link from Forgot password? |
| Invite page says “Could not accept the invitation.” | Invite expired (14 days) or was revoked | Ask a console admin to re-invite you from Settings → Staff & roles |
| You keep being returned to the sign-in page | Your session expired (typically after 24 hours) | Sign in again — you’ll be returned to where you were |
| You can sign in but a page from this guide is missing | Your role lacks the view permission, or the feature isn’t on your plan | Ask whoever manages Staff & roles; for feature-gated pages (Exchange rates, Subscriptions, Rebates, Search merchandising), ask your operator |
| Message says your organization is pending or suspended | The organization itself isn’t active | Contact your operator — this isn’t about your account |
Catalog and imports
| Symptom | Likely cause | Fix |
|---|---|---|
| Save disabled on the product dialog | SKU or Name is empty — the only two required fields | Fill both; the red asterisks mark them |
| No Photos / Draft with AI / languages / visibility on a new product | Those tools appear only after first save | Save, then re-open the product |
| “Upload failed” adding a photo | Not an image, or over 25 MB | Use JPEG/PNG/GIF/WebP under 25 MB |
| “Cannot delete” — “Category is in use” | Something still references the category | Unlink it first, then delete |
| “Saved, but categories failed” | Product saved but category links didn’t | Re-open the product and re-assign Categories |
| Import preview full of error rows | Wrong column headers, or values failing validation rules | Download the “Template” and rebuild your file; read each row’s Detail message |
| “Commit import” greyed out | Dry run hasn’t validated, or zero rows to create/update | Upload a file and wait for validation; fix errors if every row failed |
| Rows silently missing after commit | “Rows with errors are skipped on commit.” | Fix those rows and re-upload with a match field set so they update, not duplicate |
| “Draft missing descriptions” changed nothing | It only fills blanks — never overwrites | Edit existing copy per-product with Draft with AI |
Quotes and RFQs
| Symptom | Likely cause | Fix |
|---|---|---|
| Quote editor banner “This quote is ‹status› and can no longer be edited.” | Accepted, declined, and expired quotes are final | Create a new quote for the customer |
| Send appears to do nothing new | Every send is a new version — check the “Sent (vN)” toast and version tag | Nothing to fix; the buyer sees the latest version |
| Fulfilment shows “No rates for the customer’s destination” | No shipping-rate row matches the buyer’s country | Add one at Pricing → Tax & shipping, or send with “No service (price at order)” |
| Totals tagged “includes unsaved lines” | Line edits not yet saved | Press “Save lines” |
| An RFQ was quoted “by itself” | The “Instant quotes for RFQs” automation did it | That’s the feature (RFQs); check Automation → Automation runs for the firing |
| Buyer says they can’t accept the quote | The quote passed its validity date and expired | Send a fresh version; the hourly sweep expires stale quotes |
Orders and fulfilment
| Symptom | Likely cause | Fix |
|---|---|---|
| “Transition failed” on confirmed, mentioning stock | A tracked line can’t be reserved | Receive stock (Adjust stock, type receipt) or tick Allow backorder in level config, then retry |
| “Transition failed” on shipped — “create shipments covering every line…” | Shipments don’t yet cover every ordered quantity | Create shipments for the remainder (Shipments), then retry |
| “Transition failed” — “blocked: amount … exceeds the approval limit” | The order is over the buyer’s spending limit and awaits their approver | Nothing on your side — the buying company’s approver must release it |
| Order arrived on_hold | Over the buyer’s spending limit or the company credit limit | Wait for the company approver, or resolve limits with the customer (Customers, Company accounts) |
| Buyer’s order was blocked at checkout over budget | A cost-center budget would be exceeded — blocked, not held | Raise/adjust the budget on the company’s Budgets tab, or the buyer waits for the next period |
| Shipment quantity won’t go higher | Quantities are “capped at ordered minus already shipped” | That’s the cap working; ship the rest on a later shipment |
Invoices and payments
| Symptom | Likely cause | Fix |
|---|---|---|
| No “Record payment” button | Balance is zero or the invoice is void — it shows “Settled in full” | Nothing to record |
| Payment rejected as a duplicate | Same Reference recorded before — duplicate protection | Verify against the bank statement; if genuinely distinct, use the real distinct reference |
| “Download PDF” missing or stale | The PDF renders in the background | Press “Regenerate PDF” (“PDF generation enqueued”) and refresh shortly; if it never appears, the background worker may be down — tell your operator |
| Invoices never flip to overdue | The dunning automation is off and nobody runs the sweep | Enable invoice dunning (Automation → Prebuilt automations) or press “Run overdue sweep” on AR aging |
| “Refund failed” | The gateway refused the refund | Read the toast detail; verify the payment’s status and gateway configuration with your operator |
Marketplace
| Symptom | Likely cause | Fix |
|---|---|---|
| Vendor says their product isn’t on the storefront | It hasn’t been approved | Approve it in Marketplace → Catalog moderation — unapproved listings never show |
| “No payout generated — Nothing to pay out” | No delivered, unpaid sub-orders exist yet | Payouts only gather delivered sub-orders — check the vendor’s order statuses |
| Vendor lost their invite link | Invites expire after 14 days | Re-share from the approval dialog, or ask the vendor to re-apply / add them a portal user directly |
| Disbursement failed | Payout account misconfigured or gateway error | Fix the vendor’s Payout account in their profile, then press Retry |
Emails, automations, and background tasks
| Symptom | Likely cause | Fix |
|---|---|---|
| Invites, resets, or order emails not arriving | Email sending is done by a background service; it may be down or the sender misconfigured | Check Settings → Configuration → Store identity for the “Sender not aligned” warning; if settings look right, tell your operator |
| Automation runs stuck at Queued | The background worker isn’t running | Tell your operator; runs will drain once it’s back |
| Media stuck at processing | Renditions are generated in the background | The original still serves; if it never becomes ready, tell your operator |
| A feed shows failing on the dashboard | Required channel fields unmapped or missing data | Open the feed, check the unmapped-fields flags, and fix product data via Data health |