vercel/next.js · error

id property is required for every item returned from generat

Error message

id property is required for every item returned from generateImageMetadata

What it means

Thrown at request time (inside the GET handler of the generated multi-variant image route entry) when `generateImageMetadata()` returns an array in which one or more items have no `id` property (or `id == null`). Each variant must be addressable by id so Turbopack can build the `/[__metadata_id__]` segment, so the wrapper runs `imageMetadata.find(item => { if (item?.id == null) throw ... })`. Every returned item needs a unique, stringifiable `id`.

Source

Thrown at crates/next-core/src/next_app/metadata/route.rs:448

            if (typeof handler !== 'function') {{
                throw new Error('Default export is missing in {resource_path}')
            }}

            export async function GET(_, ctx) {{
                const paramsPromise = ctx.params
                const idPromise = paramsPromise.then(params => params?.__metadata_id__)
                const restParamsPromise = paramsPromise.then(params => {{
                    if (!params) return undefined
                    const {{ __metadata_id__, ...rest }} = params
                    return rest
                }})

                const restParams = await restParamsPromise
                const __metadata_id__ = await idPromise
                const imageMetadata = await generateImageMetadata({{ params: restParams }})
                const id = imageMetadata.find((item) => {{
                    if (item?.id == null) {{
                        throw new Error('id property is required for every item returned from generateImageMetadata')
                    }}

                    return item.id.toString() === __metadata_id__
                }})?.id

                if (id == null) {{
                    return new NextResponse('Not Found', {{
                        status: 404,
                    }})
                }}

                return handler({{ params: restParamsPromise, id: idPromise }})
            }}

            export * from {resource_path}

            export async function generateStaticParams({{ params }}) {{
                const imageMetadata = await generateImageMetadata({{ params }})

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Ensure every object returned by `generateImageMetadata` has a truthy `id` (string or number): `[{ id: 'light', ... }, { id: 'dark', ... }]`.
2. Check for conditional ids that can evaluate to undefined/null and provide a fallback id.
3. Filter out placeholder/empty entries before returning them.
4. After fixing, the dev server will regenerate static params and the GET handler will resolve the matching id.

Example fix

// before
export async function generateImageMetadata() {
  return [
    { alt: 'Light' },
    { alt: 'Dark', id: 'dark' },
  ]
}

// after — every item needs an id
export async function generateImageMetadata() {
  return [
    { id: 'light', alt: 'Light' },
    { id: 'dark', alt: 'Dark' },
  ]
}

// Validate the generateImageMetadata output shape before returning.
function assertImageMetadata(items: unknown[]): Array<{ id: string | number }> {
  for (const item of items) {
    if (item == null || (item as any).id == null) {
      throw new Error('generateImageMetadata: every item needs a non-null `id`')
    }
  }
  return items as Array<{ id: string | number }>
}
export async function generateImageMetadata() {
  return assertImageMetadata([{ id: 'light' }, { id: 'dark' }])
}

function hasId(item: unknown): item is { id: string | number } {
  return typeof item === 'object' && item !== null && ['string','number'].includes(typeof (item as any).id)
}

When it happens

Trigger: Writing `export async function generateImageMetadata() { return [{ alt: 'logo' }, { alt: 'logo2' }] }` — no `id` on either item — then requesting any /icon route. The find() loop hits the first item, sees `item.id == null`, and throws.

Common situations: Returning plain objects without ids; returning a promise of objects whose `id` is conditionally set; mixing variant configs where only some carry `id`; copying a generic metadata array into generateImageMetadata.

Related errors

• id property is required for every item returned from generat
• [inspect] ${route}: not an App Router document (no __next_f)
• Default export is missing in {resource_path}
• Invalid --top value: ${topRaw}
• Invalid numeric value for --${key}: ${value}

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/89fc4153144e7478. Report an issue: GitHub.