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

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)

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

Prevention

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

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