payloadcms/payload · error · Error

Either collectionSlug, globalSlug, or widgetSlug must be pro

Error message

Either collectionSlug, globalSlug, or widgetSlug must be provided

What it means

A plain Error thrown by buildFormState when none of collectionSlug, globalSlug, or widgetSlug is supplied in the args. The function needs at least one entity identifier to locate the schema; absent all three it cannot proceed.

Source

Thrown at packages/ui/src/utilities/buildFormState.ts:128

      i18n,
      payload,
      payload: { config },
    },
    returnLivePreviewURL,
    returnLockStatus,
    returnPreviewURL,
    widgetSlug,
    schemaPath = collectionSlug || globalSlug || widgetSlug,
    select,
    skipClientConfigAuth,
    skipValidation,
    updateLastEdited,
  } = args

  const selectMode = select ? getSelectMode(select) : undefined

  if (!collectionSlug && !globalSlug && !widgetSlug) {
    throw new Error('Either collectionSlug, globalSlug, or widgetSlug must be provided')
  }

  const schemaMap = getSchemaMap({
    collectionSlug,
    config,
    globalSlug,
    i18n,
    widgetSlug,
  })

  const clientSchemaMap = getClientSchemaMap({
    collectionSlug,
    config: getClientConfig({
      config,
      i18n,
      importMap: req.payload.importMap,
      user: skipClientConfigAuth ? true : req.user,
    }),

View on GitHub (pinned to 00c58b35c0)

Solutions

Ensure the caller passes at least one of collectionSlug, globalSlug, or widgetSlug to buildFormState.
Add a client-side guard so the RPC is not issued when the slug is missing.
Check the form/drawer configuration that constructs the buildFormState args.

Example fix

// before
await buildFormState({ schemaPath: undefined })

// after
if (!collectionSlug && !globalSlug && !widgetSlug) {
  throw new Error('Cannot build form state: provide a collectionSlug, globalSlug, or widgetSlug')
}
await buildFormState({ collectionSlug, schemaPath: collectionSlug })

Defensive patterns

Strategy: validation

Validate before calling

function hasEntityIdentifier(args: { collectionSlug?: string; globalSlug?: string; widgetSlug?: string }): boolean {
  return Boolean(args.collectionSlug || args.globalSlug || args.widgetSlug)
}

if (!hasEntityIdentifier({ collectionSlug, globalSlug, widgetSlug })) {
  throw new Error('Provide a collectionSlug, globalSlug, or widgetSlug')
}

Type guard

function isMissingEntityError(err: unknown): err is Error {
  return err instanceof Error && /collectionSlug, globalSlug, or widgetSlug/i.test(err.message)
}

Try / catch

try {
  await buildFormState(args)
} catch (err) {
  if (isMissingEntityError(err)) {
    // fix the caller to pass an entity identifier
    return
  }
  throw err
}

Prevention

Always pass at least one entity identifier when invoking buildFormState.
Add a client-side guard so the RPC is not issued with empty slugs.
Type the args so at least one slug is required (a discriminated union).

When it happens

Trigger: buildFormState (or the form-state server function wrapping it) is called with an args object where collectionSlug, globalSlug, and widgetSlug are all undefined — e.g. a misconfigured form drawer, a widget invocation missing its slug, or a client RPC that omitted the entity.

Common situations: A custom form/drawer instantiated without passing the collection/global slug; a widget server function called without widgetSlug; refactoring that dropped the required prop; client-side state that conditionally sets the slug ending up undefined.

Related errors

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