payloadcms/payload · error · APIError

ERROR: Failed to retrieve global with the slug "${globalSlug

Error message

ERROR: Failed to retrieve global with the slug "${globalSlug}". Does not exist.

What it means

Thrown by `getGlobal` when `payload.config.globals.find()` returns no match for `globalSlug`. The global is not registered at runtime, so no config/model lookup can proceed.

Source

Thrown at packages/db-mongodb/src/utilities/getEntity.ts:73

  globalSlug: string
}

interface GetGlobal {
  (args: { versions?: false | undefined } & BaseGetGlobalArgs): {
    globalConfig: SanitizedGlobalConfig
    Model: GlobalModel
  }
  (args: { versions?: true } & BaseGetGlobalArgs): {
    globalConfig: SanitizedGlobalConfig
    Model: CollectionModel
  }
}

export const getGlobal: GetGlobal = ({ adapter, globalSlug, versions = false }) => {
  const globalConfig = adapter.payload.config.globals.find((each) => each.slug === globalSlug)

  if (!globalConfig) {
    throw new APIError(
      `ERROR: Failed to retrieve global with the slug "${globalSlug}". Does not exist.`,
    )
  }

  if (versions) {
    const Model = adapter.versions[globalSlug]

    if (!Model) {
      throw new APIError(
        `ERROR: Failed to retrieve global version model with the slug "${globalSlug}". Does not exist.`,
      )
    }

    return { globalConfig, Model }
  }

  return { globalConfig, Model: adapter.globals } as any
}

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Verify the slug equals a `slug` in your `globals` config.
2. Confirm the global is registered and `payload.init()` resolved.
3. For dynamic slugs, validate against `payload.config.globals` first.
4. Check REST route spelling against the configured global slug.

Example fix

// before
await payload.findGlobal({ slug: 'nav' }) // real slug is 'navigation'
// after
await payload.findGlobal({ slug: 'navigation' })

function assertGlobalExists(payload, slug) {
  if (!payload.config.globals.some(g => g.slug === slug))
    throw new Error(`Global not registered: ${slug}`)
}

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

try { await payload.findGlobal({ slug }) }
catch (e) { if (/Failed to retrieve global with the slug/.test(e.message)) handleUnknownGlobal(slug) else throw e }

When it happens

Trigger: Any global operation (findGlobal, updateGlobal, etc.) with a `globalSlug` that is not in `payload.config.globals`.

Common situations: Slug typo; global renamed without updating callers; wrong config loaded in a multi-tenant setup; querying before init; REST path to a non-existent global.

Related errors

• Global with the slug ${globalSlug} was not found
• Collection with the slug ${globalSlug} was not found
• Assertion for DB name of ${name} ${slug} was failed.
• ERROR: Failed to retrieve collection with the slug "${collec
• ERROR: Failed to retrieve global version model with the slug

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