medusajs/medusa · warning

'zone' property is missing from the widget config.

Error message

'zone' property is missing from the widget config.

What it means

The widgets generator requires every widget config (created with defineWidgetConfig) to declare a `zone` property telling the admin where to inject the widget. If the parsed config has no zone, the widget cannot be placed and is skipped with this warning.

Source

Thrown at packages/admin/admin-vite-plugin/src/widgets/generate-widgets.ts:146

  if (!fileHasDefaultExport) {
    return null
  }

  let zone: InjectionZone[] | null

  try {
    zone = await getWidgetZone(ast, file)
  } catch (e) {
    logger.error(`An error occurred while traversing the file.`, {
      file,
      error: e,
    })
    return null
  }

  if (!zone) {
    logger.warn(`'zone' property is missing from the widget config.`, { file })
    return null
  }

  let idOverride: string | null = null

  try {
    idOverride = getWidgetIdOverride(ast)
  } catch (e) {
    logger.error(`An error occurred while reading the widget id.`, {
      file,
      error: e,
    })
  }

  const import_ = generateImport(file, index)
  const widget = generateWidget(zone, index, getWidgetId(idOverride, file))

  return {

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Add a valid `zone` property to defineWidgetConfig, e.g. zone: "product.details.after"
2. Pass zone as a string or an array of strings for multiple zones
3. Restart the dev server

Example fix

// before
export const config = defineWidgetConfig({ render: MyWidget })

// after
export const config = defineWidgetConfig({
  zone: "product.details.after",
})

export default MyWidget

const hasZone = (c: object): c is { zone: string | string[] } =>
  "zone" in c && (typeof (c as any).zone === "string" || Array.isArray((c as any).zone))

When it happens

Trigger: A file in src/admin/widgets whose config export lacks a `zone` key, e.g. only `{ render: MyWidget }`.

Common situations: Widget created from a component file without the config; zone key typo'd as `zones` or `Zone`.

Related errors

• 'zone' property is not a valid injection zone.
• 'zone' property is not a string or array.
• 'zone' property cannot be a template literal (e.g. `product.
• Invite with id: ${id} was not found
• The user is already authenticated and cannot accept an invit

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