payloadcms/payload · error · APIError

The global with slug ${String(globalSlug)} can't be found.

Error message

The global with slug ${String(globalSlug)} can't be found.

What it means

Thrown by findGlobalVersionByIDLocal when globalSlug is not in payload.globals.config, before delegating to findVersionByIDOperation. The Local API wrapper that backs payload.findGlobalVersionByID.

Source

Thrown at packages/payload/src/globals/operations/local/findVersionByID.ts:96

export async function findGlobalVersionByIDLocal<TSlug extends GlobalSlug>(
  payload: Payload,
  options: Options<TSlug>,
): Promise<TypeWithVersion<DataFromGlobalSlug<TSlug>>> {
  const {
    id,
    slug: globalSlug,
    depth,
    disableErrors = false,
    overrideAccess = true,
    populate,
    select,
    showHiddenFields,
  } = options

  const globalConfig = payload.globals.config.find((config) => config.slug === globalSlug)

  if (!globalConfig) {
    throw new APIError(`The global with slug ${String(globalSlug)} can't be found.`)
  }

  return findVersionByIDOperation({
    id,
    depth,
    disableErrors,
    globalConfig,
    overrideAccess,
    populate,
    req: await createLocalReq(options as CreateLocalReqOptions, payload),
    select,
    showHiddenFields,
  })
}

View on GitHub (pinned to 00c58b35c0)

Solutions

  1. Guard the slug with a check against payload.globals.config.
  2. Use the typed GlobalSlug parameter so invalid slugs fail at compile time.
  3. Update callers after a rename; do not rely on silent null.
  4. Verify Payload init completed.

Example fix

// before
const v = await payload.findGlobalVersionByID({ slug: 'navigaton', id })

// after
const exists = payload.globals.config.some(g => g.slug === slug)
if (!exists) throw new Error(`Unknown global: ${slug}`)
const v = await payload.findGlobalVersionByID({ slug, id })
Defensive patterns

Strategy: validation

Validate before calling

if (!payload.globals.config.some((g) => g.slug === slug)) {
  throw new Error(`Unknown global: ${slug}`)
}

Type guard

function isGlobalSlug(payload: Payload, slug: string): slug is GlobalSlug {
  return payload.globals.config.some((g) => g.slug === slug)
}

Try / catch

try {
  return await payload.findGlobalVersionByID({ slug, id })
} catch (err) {
  if (err instanceof APIError && /can't be found/.test(err.message)) return null
  throw err
}

Prevention

When it happens

Trigger: Calling payload.findGlobalVersionByID({ id, slug: 'wrong' }) where the slug is not registered.

Common situations: Slug typo; renamed global; copy-paste; calling during boot before globals are sanitized.

Related errors

AI-assisted analysis of payloadcms/payload@00c58b35c0 (2026-08-12). Data as JSON: /api/errors/00d05b57c7ee55d9. Report an issue: GitHub.