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 restoreGlobalVersionLocal (payload.restoreGlobalVersion) when globalSlug is not registered. Guard before delegating to restoreVersionOperation.

Solutions

1. Validate the slug against payload.globals.config before calling.
2. Use typed GlobalSlug constants for restore scripts.
3. After a rename, sweep all restore call sites.
4. Confirm versions are enabled on the target global.

Example fix

// before
await payload.restoreGlobalVersion({ slug: 'configg', id })

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

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

When it happens

Trigger: Calling payload.restoreGlobalVersion({ id, slug: 'unknown' }) with a slug absent from payload.globals.config.

Common situations: Slug typo; renamed global; restoring from a script with a hardcoded stale slug; 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/773acb547d5afe07. Report an issue: GitHub.

Appendix: source

Thrown at packages/payload/src/globals/operations/local/restoreVersion.ts:73

   * the Global slug to operate against.
   */
  slug: TSlug
  /**
   * If you set `overrideAccess` to `false`, you can pass a user to use against the access control checks.
   */
  user?: null | User
}

export async function restoreGlobalVersionLocal<TSlug extends GlobalSlug>(
  payload: Payload,
  options: Options<TSlug>,
): Promise<DataFromGlobalSlug<TSlug>> {
  const { id, slug: globalSlug, depth, overrideAccess = true, populate, 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 restoreVersionOperation({
    id,
    depth,
    globalConfig,
    overrideAccess,
    populate,
    req: await createLocalReq(options as CreateLocalReqOptions, payload),
    showHiddenFields,
  })
}

View on GitHub (pinned to 00c58b35c0)