medusajs/medusa · error · MedusaError

invalid_data

invalid_data

Error message

Cannot complete a cart with no items

What it means

The store gift-card route queries the loyalty module by code (or id); when no gift card matches, it returns MedusaError NOT_FOUND 'Gift card not found'. This is the standard 404 path for unknown/invalid codes.

Source

Thrown at packages/core/core-flows/src/cart/steps/validate-cart-items.ts:41

/**
 * This step validates that a cart has at least one line item before
 * completing the cart and placing an order. If the cart has no items,
 * the step throws an error.
 *
 * @example
 * validateCartItemsStep({
 *   cart
 * })
 *
 * @since 2.14.3
 */
export const validateCartItemsStep = createStep(
  validateCartItemsStepId,
  async (data: ValidateCartItemsStepInput) => {
    const { cart } = data

    if (!cart.items?.length) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        `Cannot complete a cart with no items`
      )
    }

    return new StepResponse(void 0)
  }
)

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Verify the exact code, trimmed and case-corrected, against the gift card in admin
2. Catch NOT_FOUND and show a friendly 'invalid code' message to the customer
3. Ensure the gift card exists and is active in the same store scope before offering it

Example fix

// before
const { gift_card } = await sdk.store.giftCard.retrieve(code)
// after
try { const { gift_card } = await sdk.store.giftCard.retrieve(code) } catch (e) { if (e.type === 'not_found') return showInvalidCodeMessage() throw e }

const gift_card = await query.graph({ entity: 'gift_card', filters: { code } }).then(r => r.data[0] ?? null)
if (!gift_card) return invalidCodeResponse()

try { const { gift_card } = await sdk.store.giftCard.retrieve(code) } catch (e) { if (e.type === 'not_found') return showInvalidCode(); throw e }

When it happens

Trigger: GET /store/gift-cards/{code} where the code doesn't match any gift card — mistyped code, deleted gift card, or looking up by a code scoped to another channel/store.

Common situations: Checkout forms where the customer pastes an invalid/expired code; gift cards created in a different environment; codes with case or whitespace differences.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• invalid_data
• NOT_FOUND
• NOT_FOUND
• NOT_FOUND
• NOT_FOUND

AI-assisted analysis of medusajs/medusa@5e06e544a2 (2026-08-27). Data as JSON: /api/errors/76bcb3ee7be55bf1. Report an issue: GitHub.