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 findGlobalVersionsLocal (payload.findGlobalVersions) when the supplied globalSlug does not match any sanitized global config. Entry guard before the versions query runs.

Source

Thrown at packages/payload/src/globals/operations/local/findVersions.ts:116

): Promise<PaginatedDocs<TypeWithVersion<DataFromGlobalSlug<TSlug>>>> {
  const {
    slug: globalSlug,
    depth,
    limit,
    overrideAccess = true,
    page,
    pagination = true,
    populate,
    select,
    showHiddenFields,
    sort,
    where,
  } = 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 findVersionsOperation({
    depth,
    globalConfig,
    limit,
    overrideAccess,
    page,
    pagination,
    populate,
    req: await createLocalReq(options as CreateLocalReqOptions, payload),
    select,
    showHiddenFields,
    sort,
    where,
  })
}

View on GitHub (pinned to 00c58b35c0)

Solutions

  1. Validate the slug against payload.globals.config first.
  2. Use typed GlobalSlug at the call boundary.
  3. Search-and-replace after renaming a global.
  4. Ensure payload.init() resolved.

Example fix

// before
const res = await payload.findGlobalVersions({ slug: 'footr' })

// after
if (!payload.globals.config.some(g => g.slug === slug)) {
  throw new Error(`Unknown global slug: ${slug}`)
}
const res = await payload.findGlobalVersions({ slug })
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.findGlobalVersions({ slug })
} catch (err) {
  if (err instanceof APIError && /can't be found/.test(err.message)) return { docs: [], totalDocs: 0 }
  throw err
}

Prevention

When it happens

Trigger: Calling payload.findGlobalVersions({ slug: 'typo' }) with an unregistered slug.

Common situations: Slug typo, post-rename stale reference, dynamic slug from unvalidated input, calling before init.

Related errors

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