Troubleshooting Publish Errors

When the Push to eBay button surfaces an error, the message is usually eBay's API error verbatim. They're not always friendly. This page translates the most common ones and tells you what to do.

If you don't see your error here, the eBay developer error reference has the full list keyed by errorId.

Pre-publish errors (readiness panel)

These show up in the Listing readiness panel on the card detail page BEFORE you click Push. Fix them and the publish button enables.

"Add at least one photo. eBay rejects listings without an image."

What it means: the card has zero card_image rows attached.

Fix: scroll down to the Media section on the card detail page and upload at least one photo. Front-of-card is required; back-of-card is recommended for graded slabs (buyers expect to see the cert # on the back of the slab).

"Card name is empty. Buyers search by card name first."

What it means: card.name is null or whitespace.

Fix: scroll to the Product section, fill in the Name field. For Pokemon, this is just the character name ("Pawmot", "Charizard"). For sports, use the player's full name ("Mike Trout", not "Trout"). For unidentified cards, run the Identify with AI button first.

"Asking price is missing or zero. Set a price before publishing."

What it means: card.asking_price is null or ≤ 0.

Fix: scroll to the Pricing section and set a positive number. If you don't know the price, use the Comp Research panel (or open in PriceCharting) to find what similar cards sold for.

"$X card exceeds USPS Priority Express's $5,000 insurance cap..."

What it means: this card triggered the Grail tier ($5,000+) acknowledgment. AICV will still let you publish, but the standard handling fee won't cover the full insurance — you need to manually buy USPS Registered Mail or a third-party rider at label-print time.

Fix: read the warning, plan the shipping accordingly. The block is a "required" blocker for visibility, not because publishing is technically broken. See Label-Print Workflow for the Grail-tier section.

Post-publish errors (toast surfaces "HTTP 502" or "Push to eBay failed")

These hit eBay's API and get rejected. The error message in the toast is the most-actionable piece — match it against this list.

Offer entity already exists (errorId 25002)

What it means: a previous publish attempt for this card created an offer on eBay's side but failed before publishing. The orphan offer is now blocking new offers for the same SKU.

Fix: AICV auto-recovers — it detects the orphan, deletes it, and creates a fresh one. If the error persists after a retry, it means recovery itself failed (rare). Check that your eBay account is still connected (/connections/ebay/overview should show status "Connected").

Condition data is required for selected category 183454 (errorId 25058)

What it means: the listing's top-level condition field is missing for a graded-slab listing in CCG Individual Cards.

Fix: AICV should be sending LIKE_NEW for all graded cards as of the descriptor-IDs fix. If you're seeing this error, your local build might be behind — check Settings → eBay → Business Policies and re-apply.

Condition descriptor 40002 is not valid (errorId 25060)

What it means: AICV is sending the wrong descriptor IDs for the graded-card grading fields.

Fix: this was a known bug fixed in early May 2026 — descriptor IDs 27501/27502/27503 are the correct ones for trading cards (not 40001/40002/40003). If you're seeing this on a fresh deploy, please file an issue.

Descriptor information sent as NULL... Certification Number (27503) (errorId 25066)

What it means: eBay's pipeline is registering the cert# descriptor as null even when we send a real value.

Fix: AICV intentionally OMITS descriptor 27503 today. The cert # still gets surfaced on the listing via the item-specific aspect ("Certification Number"). If you're seeing this error in 2026 or later, it means a build artifact is sending the old code.

Package weight is not valid or is missing (errorId 25020)

What it means: card.shipping_weight_oz is null. Calculated shipping needs a weight to quote postage.

Fix: AICV's createCard flow universally defaults shipping weight (graded=3oz, raw=1oz). If a card slipped through without one, check the Shipping section on the card detail page and set the weight manually. 3 oz for graded slabs; 1 oz for raw cards in a bubble mailer.

Invalid value for aspect [Card Condition] (errorId 25002 with BrandMPN)

What it means: the Card Condition aspect value isn't in eBay's accepted list.

Fix: eBay accepts only 4 values for CCG card condition — Near Mint or Better / Excellent / Very Good / Poor. AICV maps the TCG-industry vocabulary (M/NM/LP/MP/HP/DMG) to these. If you see this error, check the card's Condition field — it might be set to a custom value not in our mapping.

merchant_location_missing

What it means: your eBay account doesn't have a merchant-location key set up, so calculated shipping can't quote postage.

Fix: go to Connections → eBay → My Locations and set up a primary location (city + ZIP at minimum). Or run through onboarding again — the where-from step handles this automatically. The Business Policies panel on Overview will show a "Set location first" hint until you do.

business_policies_missing

What it means: the publish flow couldn't resolve one of payment / return / fulfillment policies. Either none are installed, or the auto-pick + batch + user-default chain all failed.

Fix: go to Connections → eBay → Overview and click "Re-apply all recommended" in section 03. Idempotent — already-present policies are skipped.

HTTP 502 with no detail in the toast

What it means: either eBay's API call timed out from our handler, OR a reverse-proxy is returning 502 because the upstream got stuck.

Fix: try the push again — the most common cause is a transient eBay API hiccup. If it fails 3 times in a row, check /connections/ebay/overview to confirm your eBay connection is still healthy. If everything looks fine and it keeps 502-ing, file an issue with the specific timestamp.

Image errors

"Image not available" on the live listing

What it means: eBay's CDN tried to fetch our HMAC-signed image URL and got bounced.

Fix: this was a middleware bug fixed in early May 2026 — the /api/images/* path is now in PUBLIC_PREFIXES so eBay's anonymous CDN can fetch signed URLs without getting redirected to /signin. If you see this on a freshly published listing, end the listing and re-publish to trigger a fresh image scrape.

Account-level errors

ebay_not_connected

What it means: the OAuth token we have for your eBay account is no longer valid (expired, revoked, or the user changed their eBay password).

Fix: go to Connections → eBay → Overview and click Reconnect. Your saved policies, locations, and templates persist — only the auth token is rebuilt.

403 Access denied from getItemAspectsForCategory

What it means: AICV is hitting eBay's Taxonomy API to check required aspect names but doesn't have the right OAuth scope.

Fix: this is non-fatal — the call is wrapped in a try/catch and the publish flow continues. The only impact is that AICV's aspect-coverage warning ("missing aspect: X") is silent. We're tracking the missing scope (commerce.taxonomy) for a future OAuth re-grant.

What to do when you see a NEW error

1. Take a screenshot of the toast OR the network response body
2. Open /connections/ebay/overview and confirm:
   • eBay connection still healthy (section 01)
   • At least 1 payment + 1 return + 1 fulfillment policy installed (section 03)
   • Merchant location set up
3. Try a different card. If the new card publishes fine, the issue is card-specific (probably an aspect or condition value). If multiple cards fail, the issue is account-wide.
4. File an issue with the toast text + the card's asking price + isGraded status.