payloadcms/payload · error · Forbidden

error:notAllowedToPerformAction

Error message

error:notAllowedToPerformAction

What it means

Thrown at the top of `registerFirstUser` when `config.auth.disableLocalStrategy` is true. This collection delegates authentication to an external/SSO/JWT strategy, so Payload refuses to create a first local user. `Forbidden` (HTTP 403).

Source

Thrown at packages/payload/src/auth/operations/registerFirstUser.ts:47

export const registerFirstUserOperation = async <TSlug extends AuthCollectionSlug>(
  args: Arguments<TSlug>,
): Promise<Result<DataFromCollectionSlug<TSlug>>> => {
  const {
    collection: {
      config,
      config: {
        slug,
        auth: { verify },
      },
    },
    data,
    req,
    req: { payload },
  } = args

  if (config.auth.disableLocalStrategy) {
    throw new Forbidden(req.t)
  }

  try {
    const shouldCommit = await initTransaction(req)

    ensureUsernameOrEmail<TSlug>({
      authOptions: config.auth,
      collectionSlug: slug,
      data,
      operation: 'create',
      req,
    })

    const where = appendNonTrashedFilter({
      enableTrash: Boolean(config.trash),
      trash: false,
      where: {}, // no initial filter; just exclude trashed docs
    })

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Remove the `registerFirstUser` call for collections with `disableLocalStrategy: true`; create the initial user through your external IdP instead.
2. If you actually want local users, set `disableLocalStrategy: false` (or omit it).
3. Guard the seeding step: `if (!config.auth.disableLocalStrategy) await payload.registerFirstUser(...)`.

Example fix

// before
await payload.registerFirstUser({ collection: 'users', data, req })
// after
if (!collectionConfig.auth.disableLocalStrategy) {
  await payload.registerFirstUser({ collection: 'users', data, req })
}

// Skip first-user registration for external-strategy collections
if (collectionConfig.auth.disableLocalStrategy) {
  throw new Error('Cannot register a local first user on an external-strategy collection')
}
await payload.registerFirstUser({ collection, data, req })

function usesLocalStrategy(cfg: CollectionConfig): boolean {
  return !cfg.auth?.disableLocalStrategy
}

if (collectionConfig.auth.disableLocalStrategy) {
  // bootstrap via IdP instead
} else {
  await payload.registerFirstUser({ collection, data, req })
}

When it happens

Trigger: A collection is configured with `auth: { disableLocalStrategy: true }` (e.g. delegating to a third-party IdP) and the first-user registration endpoint is hit. The operation exists only for local-strategy bootstrapping, so it bails immediately.

Common situations: A boilerplate/template that always calls `registerFirstUser` on setup, applied to a collection configured for SSO; mislabeling a collection as auth-enabled-for-external; enabling `disableLocalStrategy` without removing the first-user seeding script.

Related errors

• error:notAllowedToPerformAction
• error:notAllowedToPerformAction
• error:notAllowedToPerformAction
• No auth config found for collection: ${collection}
• No auth config found for collection: ${collection}

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