Labels and external integrations
Symptoms
Fulfillment sits in LABEL_CREATION_FAILED. A webhook returns 401. Forgot-password returns success and no email arrives. R2 public URLs 404.
Likely causes
| Symptom | Where to look |
|---|---|
LABEL_CREATION_FAILED | Courier strategy ship(), then the fulfillment map. Retry is a transition back to LABEL_CREATING, not only Bull |
| Courier accepted a shipment PointNXT does not have | The HTTP call is outside the database transaction. Automatic cancel was not verified |
| Webhook 401 | Signature check. WhatsApp rejects unsigned bodies when META_APP_SECRET is unset. Shopify has a verification path. Other couriers must be checked per controller |
| Email never arrives | email_queue job password-reset-email. The HTTP API still returns success. SMTP host set without port or from-address fails boot, not the request |
| Public file URL 404 on R2 | AWS_S3_PUBLIC_URL unset. The env comment describes that fallback |
| Channel test connection fails | Vault credentials on IntegrationConnection, plus env for app-level Amazon keys |
| Seeded courier does nothing | Codes NIP, PIK, SHYP, ARMX, AMZ have no strategy class |
How to investigate
- Fulfillment status history.
- Worker logs for
batch-labels. - Sentry for the terminal Bull failure.
- The carrier shipment id, if the strategy stored one, versus the local
Shipmentrow.
Resolution
Fix credentials, move the fulfillment back through LABEL_CREATING when the map allows it, and confirm the worker is up. Do not expect the wallet token to refund itself. That rule is unknown.
Unknown
Per-carrier rate limits and the reconciliation of a label that exists only on the courier.