What causes "Global with the slug ${globalSlug} was not found" in payloadcms/payload?

Verify the `globalSlug` string exactly equals the `slug` property of a global in your `globals` config array.

payloadcms/payload · error · APIError

Global with the slug ${globalSlug} was not found

Error message

Global with the slug ${globalSlug} was not found

What it means

Thrown by the MongoDB adapter's query builder (getBuildQueryPlugin) when it must resolve a global's flattened field schema to translate a Payload `where` clause into a MongoDB aggregation/filter, but `payload.globals.config.find()` returns no match for the supplied `globalSlug`. Without field definitions the param parser cannot coerce or validate query values, so the adapter aborts rather than emit a silently-wrong query.

Source

Thrown at packages/db-mongodb/src/queries/getBuildQueryPlugin.ts:43

}: GetBuildQueryPluginArgs = {}) => {
  return function buildQueryPlugin(schema: any) {
    const modifiedSchema = schema
    async function schemaBuildQuery({
      globalSlug,
      locale,
      payload,
      where,
    }: BuildQueryArgs): Promise<Record<string, unknown>> {
      let fields: FlattenedField[] | null = null

      if (versionsFields) {
        fields = versionsFields
      } else {
        if (globalSlug) {
          const globalConfig = payload.globals.config.find(({ slug }) => slug === globalSlug)

          if (!globalConfig) {
            throw new APIError(`Global with the slug ${globalSlug} was not found`)
          }

          fields = globalConfig.flattenedFields
        }
        if (collectionSlug) {
          const collectionConfig = payload.collections[collectionSlug]?.config

          if (!collectionConfig) {
            throw new APIError(`Collection with the slug ${globalSlug} was not found`)
          }

          fields = collectionConfig.flattenedFields
        }
      }

      if (fields === null) {
        throw new APIError('Fields are not initialized.')
      }

View on GitHub (pinned to 00c58b35c0)

Solutions

Verify the `globalSlug` string exactly equals the `slug` property of a global in your `globals` config array.
Confirm the global is actually passed to `payload.init({ globals: [...] })` (or auto-loaded) and that init has resolved.
If the slug is dynamic/user-supplied, validate it against `payload.config.globals` before issuing the query.
Check for duplicate or shadowing global configs that change which slug resolves.

Example fix

// before
await payload.db.collections['nonexistent-global'].find({ where: {...} })
// after
const exists = payload.config.globals.some(g => g.slug === globalSlug)
if (!exists) throw new Error(`Unknown global: ${globalSlug}`)
await payload.findGlobal({ slug: globalSlug, ... })

Defensive patterns

Strategy: validation

Validate before calling

function resolveGlobalSlug(payload, globalSlug) {
  const g = payload.config.globals.find(x => x.slug === globalSlug)
  if (!g) throw new Error(`Unknown global slug: ${globalSlug}`)
  return g
}

Type guard

const isRegisteredGlobalSlug = (payload, s) =>
  typeof s === 'string' && payload.config.globals.some(g => g.slug === s)

Try / catch

try { await payload.findGlobal({ slug, ... }) }
catch (e) { if (/Global with the slug .* was not found/.test(e.message)) handleUnknownGlobal(slug) else throw e }

Prevention

Centralize slug lookups behind a resolver that validates against payload.config.globals.
Never accept raw user input as a global slug without validation.
Await payload.init() before issuing any query.

When it happens

Trigger: Any query path that routes through buildQueryPlugin with a `globalSlug` not present in `payload.config.globals` — e.g. `req.payload.db.collections[slug]` queries, internal global queries with a `where` param, or a REST/global operation that supplies a slug not registered during init.

Common situations: Renaming a global without updating callers; slug typo; loading the wrong Payload config in a multi-tenant setup; issuing queries before `payload.init()` has finished registering globals; user/dynamic slug input that is not validated.

Related errors

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