Diagnose failed order placement

If an order remains in released after the place transition fails, read the server-owned placement diagnosis first:

bash
nucli --tenant <tenant-alias> commerce order diagnose <order-uuid>

The command does not change the order, reservations, invoices, payments, or shipments. It uses the existing orders:read permission and reports:

  • order workflow state and health;
  • the latest safe action and error code;
  • the fulfillment strategy stored on each OrderItem and the current ProductLogistics strategy;
  • each item's promotion state;
  • the current follow-up mode and the target type derived from the strategy snapshot;
  • the verified place and fulfillment.promote contract and the actual planned effects;
  • existing invoice, payment-transaction, and shipment boundaries;
  • whether the server classifies a normal place retry as safe.

Use --json to obtain the unchanged lifecycle projection for automation:

bash
nucli --tenant <tenant-alias> commerce order diagnose <order-uuid> --json

Interpret the result

placement.status=retry_ready with retrySafe=true means that the server can map the complete OrderItem graph to a supported placement path. The pinned workflow must also contain exactly one catalog-bound, transaction-safe, and replay-safe fulfillment.promote action on the place transition. This transition must lead exactly to the placed state. If this contract is missing or divergent, placement remains blocked with ERR_FULFILLMENT_WORKFLOW_CONTRACT_UNSUPPORTED.

A strategyMismatch=true value is diagnostic information: the stored OrderItem snapshot remains authoritative for that existing order. For a follow-up strategy, followUp.mode reports the current policy and followUp.targetType reports the expected target type. A manual mode means that the retry records an open demand only; it does not create a PurchaseOrder or ManufacturingOrder.

plannedEffects contains entries only when the final classification is both retry_ready and retrySafe=true. The array remains empty for an already placed order, a blocked graph, or an unsupported workflow contract.

ERR_FULFILLMENT_FOLLOW_UP_MODE_INVALID indicates an invalid current value in ProductLogistics. In this case, diagnosis omits the affected item's follow-up fields and never exposes the raw value. Do not retry placement. Use the tenant-bound PIM workflow to correct the product variant to manual or automatic, then run diagnosis again.

compatibilityMode=legacy_manual_snapshot_initialization identifies a strictly bounded historical cart state. The normal place transition may initialize its missing promotion snapshots inside the workflow root transaction. Workflow state, items, and follow-ups either commit together or roll back together.

Run a retry only as a separately approved workflow dispatch with a new idempotency key. The diagnosis does not authorize a retry and does not create an invoice, payment, email, or shipment.

If placement.status=blocked, do not apply a direct database fix or a heuristic retry. Record the reported domain codes and escalate the divergent graph as a product case. The diagnosis does not expose raw SQL, driver, provider, or customer data.