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 findGlobalLocal (the Local API findGlobal) when the supplied globalSlug is not present in payload.globals.config. Guards the operation before delegating to findOneOperation. Surfaced as APIError.

Solutions

1. Validate the slug against payload.globals.config before calling.
2. Drive callers from a typed GlobalSlug constant rather than a free string.
3. After renaming a global, update all callers and keep an alias if backward compat is required.
4. Confirm the global is declared in payload.config.globals.

Example fix

// before
const doc = await payload.findGlobal({ slug: 'stte' })

// after
const KNOWN_GLOBALS = payload.globals.config.map(g => g.slug)
if (!KNOWN_GLOBALS.includes(slug)) {
  return null
}
const doc = await payload.findGlobal({ 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.findGlobal({ slug })
} catch (err) {
  if (err instanceof APIError && /can't be found/.test(err.message)) return null
  throw err
}

When it happens

Trigger: Calling payload.findGlobal({ slug: 'mistyped' }) with a slug that does not match any registered global.

Common situations: Slug typo; renamed global; calling before init; dynamic slug resolved from user input without validation.

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/73e401b77d78c449. Report an issue: GitHub.

Appendix: source

Thrown at packages/payload/src/globals/operations/local/findOne.ts:121

): Promise<TransformGlobalWithSelect<TSlug, TSelect>> {
  const {
    slug: globalSlug,
    data,
    depth,
    disableErrors,
    draft = false,
    flattenLocales,
    includeLockStatus,
    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 findOneOperation({
    slug: globalSlug as string,
    data,
    depth,
    disableErrors,
    draft,
    flattenLocales,
    globalConfig,
    includeLockStatus,
    overrideAccess,
    populate,
    req: await createLocalReq(options as CreateLocalReqOptions, payload),
    select,
    showHiddenFields,
  })
}

View on GitHub (pinned to 00c58b35c0)