payloadcms/payload · error · APIError

The global with slug ${String(globalSlug)} can't be found. C

Error message

The global with slug ${String(globalSlug)} can't be found. Count Global Versions Operation.

What it means

Thrown by countGlobalVersionsLocal when no global in payload.globals.config matches the supplied slug. It is a guard at the entry of the Local API before any DB query runs, so a bad slug fails fast. Surfaced as an APIError (HTTP 400/500 depending on context).

Source

Thrown at packages/payload/src/globals/operations/local/countVersions.ts:59

   * If you set `overrideAccess` to `false`, you can pass a user to use against the access control checks.
   */
  user?: null | User
  /**
   * A filter [query](https://payloadcms.com/docs/queries/overview)
   */
  where?: Where
}

export async function countGlobalVersionsLocal<TSlug extends GlobalSlug>(
  payload: Payload,
  options: CountGlobalVersionsOptions<TSlug>,
): Promise<{ totalDocs: number }> {
  const { disableErrors, global: globalSlug, overrideAccess = true, where } = options

  const global = payload.globals.config.find(({ slug }) => slug === globalSlug)

  if (!global) {
    throw new APIError(
      `The global with slug ${String(globalSlug)} can't be found. Count Global Versions Operation.`,
    )
  }

  return countGlobalVersionsOperation<TSlug>({
    disableErrors,
    global,
    overrideAccess,
    req: await createLocalReq(options as CreateLocalReqOptions, payload),
    where,
  })
}

View on GitHub (pinned to 00c58b35c0)

Solutions

  1. Check payload.globals.config.some(g => g.slug === slug) before calling.
  2. Use the typed GlobalSlug union so the compiler rejects unknown slugs.
  3. Grep for the old slug after any rename and update all references.
  4. Ensure Payload has finished init (await payload.init()) before invoking Local API methods.

Example fix

// before
const { totalDocs } = await payload.countGlobalVersions({ global: 'brading' })

// after
const slug = 'branding' as const
if (!payload.globals.config.some(g => g.slug === slug)) {
  throw new Error(`Unknown global slug: ${slug}`)
}
const { totalDocs } = await payload.countGlobalVersions({ global: 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

const knownGlobals: ReadonlySet<string> = new Set(
  payload.globals.config.map((g) => g.slug),
)
function isKnownGlobal(slug: string): slug is GlobalSlug {
  return knownGlobals.has(slug)
}

Try / catch

try {
  await payload.countGlobalVersions({ global: slug })
} catch (err) {
  if (err instanceof APIError && /can't be found/.test(err.message)) return 0
  throw err
}

Prevention

When it happens

Trigger: Calling payload.countGlobalVersions({ global: 'nonexistent' }) or a slug that has a typo/case mismatch. Also when the global was renamed but the caller still uses the old slug.

Common situations: Refactoring a global slug and forgetting to update a call site; copy-paste between projects with different global names; calling the Local API during a migration before Payload has registered the global.

Related errors

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