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 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.

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)

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 })
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.findGlobal({ slug })
} catch (err) {
  if (err instanceof APIError && /can't be found/.test(err.message)) return null
  throw err
}

Prevention

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

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