medusajs/medusa · error · MedusaError

invalid_data

invalid_data

Error message

Gift card (${input.code}) not found

What it means

The validate-gift-card step in addGiftCardToCartWorkflow throws INVALID_DATA when the gift card looked up by code does not exist. This runs before any cart mutation, so the cart is unchanged.

Source

Thrown at packages/plugins/loyalty/src/workflows/carts/workflows/add-gift-card-to-cart.ts:107

   */
  giftCard: ModuleGiftCard
  /**
   * The lookup input containing the gift card code.
   */
  input: { code: string }
}

/**
 * Validate if the gift card exists.
 */
const validateGiftCardStep = createStep(
  "validate-gift-card",
  async function ({
    giftCard,
    input,
  }: ValidateGiftCardExistsStepInput) {
    if (!giftCard) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        `Gift card (${input.code}) not found`
      );
    }
  }
);

/**
 * Input to validate that gift cards can be added to a cart.
 */
export interface ValidateCartGiftCardStepInput {
  /**
   * The cart to validate against, including its currently applied gift cards.
   */
  cart: PluginCartDTO
  /**
   * The gift cards to apply to the cart.
   */

View on GitHub (pinned to 5e06e544a2)

Solutions

  1. Trim and normalize the code before invoking the workflow
  2. Verify the gift card exists (and is active) via listGiftCards before adding
  3. Return a friendly 'invalid code' message to the customer on this error

Example fix

// before
await addGiftCardToCartWorkflow.run({ input: { cart_id, code } })
// after
const code = rawCode.trim()
const [gc] = await query.graph({ entity: 'gift_card', filters: { code } })
if (gc) await addGiftCardToCartWorkflow.run({ input: { cart_id, code } })
Defensive patterns

Strategy: validation

Validate before calling

const code = rawCode.trim()
const [gc] = await query.graph({ entity: 'gift_card', filters: { code } })
if (!gc) return { error: 'Invalid gift card code' }

Try / catch

try { await workflow.run(...) } catch (e) { if (/not found/.test(e.message)) return notFoundResponse }

Prevention

When it happens

Trigger: Calling add-gift-card-to-cart with a typo'd, malformed, or deleted/disabled gift card code; the useQueryGraphStep lookup returned null/undefined.

Common situations: User pastes a code with whitespace or wrong casing, the gift card was deactivated in admin, or the code belongs to another region/currency scope not covered by the query filters.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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