payloadcms/payload · error · APIError

No global was specified

Error message

No global was specified

What it means

Thrown by `getRequestGlobal` when `req.routeParams.global` is absent or not a string. This utility resolves the target global from the request route parameters on global-scoped REST endpoints (e.g. `/api/globals/:global`).

Source

Thrown at packages/payload/src/utilities/getRequestEntity.ts:83

  }

  // If we still should sanitize, parse float
  if (shouldSanitize) {
    sanitizedID = parseFloat(sanitizedID)
  }

  return {
    // @ts-expect-error generic return
    id: sanitizedID,
    collection,
  }
}

export const getRequestGlobal = (req: PayloadRequest): SanitizedGlobalConfig => {
  const globalSlug = req.routeParams?.global

  if (typeof globalSlug !== 'string') {
    throw new APIError(`No global was specified`, 400)
  }

  const globalConfig = req.payload.globals.config.find((each) => each.slug === globalSlug)

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

  return globalConfig
}

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Ensure the request URL includes the global slug segment and the route captures it into `routeParams.global`.
2. If calling the REST layer programmatically, set `req.routeParams = { global: 'yourGlobalSlug' }` on the synthetic request.
3. Verify no middleware clears `req.routeParams` before Payload processes the request.
4. Use the Local API (`payload.findGlobal`, `payload.updateGlobal`) instead of constructing raw requests when possible.

Example fix

// before -- custom handler forwards without routeParams
app.get('/api/site-config', (req, res) => payloadGlobalHandler(req, res))

// after
app.get('/api/globals/:global', (req, res, next) => {
  req.routeParams = { global: req.params.global }
  next()
})

// Before forwarding to Payload REST, ensure routeParams.global is set
if (typeof req.routeParams?.global !== 'string') {
  throw new Error('Missing global slug in route params')
}

const hasGlobalParam = (req) => typeof req.routeParams?.global === 'string'

try {
  globalConfig = getRequestGlobal(req)
} catch (e) {
  if (e instanceof APIError && e.message === 'No global was specified') {
    // set req.routeParams.global and retry, or return 400
  } else throw e
}

When it happens

Trigger: A request reaches a global-resolution path but the route was matched without populating `routeParams.global`. Typically a misconfigured custom route, a middleware that strips route params, or an internal call missing the param.

Common situations: A custom handler forwards to Payload global REST layer without setting route params; a URL rewrite removed the global slug segment; an internal Local API call constructed a synthetic request without `routeParams.global`; a custom route pattern that fails to capture the global slug.

Related errors

• No collection was specified
• Join fields cannot be added to arrays, blocks or globals.
• This collection is not an upload collection: ${collection.co
• Collection with the slug ${collectionSlug} was not found
• ID was not specified

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