payloadcms/payload · error · APIError

The global with slug

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.

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 })

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

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

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
}

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

• The global with slug
• The global with slug
• The global with slug
• The global with slug
• The global with slug

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

Appendix: 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)