weaviate/weaviate · error

cannot create db user with root user name

Error message

cannot create db user with root user name

What it means

Weaviate's dynamic DB user management API rejects a POST /users/db request whose userID matches the reserved root user name. The root user is a built-in admin principal (typically 'root', defined in config AUTHENTICATION_APIKEY_USERS) and is not a dynamic DB user, so creating a second user under that name is forbidden. The handler checks reserved names before any RAFT/DB write, returning HTTP 422 (Unprocessable Entity) with this message in the error payload.

Source

Thrown at adapters/handlers/rest/db_users/handlers_db_users.go:442

		if err := h.dbUsers.CreateUserWithKey(ctx, params.UserID, apiKey[:3], sha256.Sum256([]byte(apiKey)), createdAt); err != nil {
			return users.NewCreateUserInternalServerError().WithPayload(cerrors.ErrPayloadFromSingleErr(principal, fmt.Errorf("creating user: %w", err)))
		}

		return users.NewCreateUserCreated().WithPayload(&models.UserAPIKey{Apikey: &apiKey})
	}

	// Skip the RAFT round-trip when the namespace is locally known not to be
	// active; the apply path re-validates authoritatively.
	if err := namespaces.RequireActive(h.namespaces, ns); err != nil {
		return renderCreateUserNamespaceErr(principal, err)
	}

	if h.staticUserExists(internalKey) {
		return users.NewCreateUserConflict().WithPayload(cerrors.ErrPayloadFromSingleErr(principal, fmt.Errorf("user '%v' already exists", params.UserID)))
	}
	if h.isRootUser(internalKey) {
		return users.NewCreateUserUnprocessableEntity().WithPayload(cerrors.ErrPayloadFromSingleErr(principal, errors.New("cannot create db user with root user name")))
	}
	if h.isAdminlistUser(internalKey) {
		return users.NewCreateUserUnprocessableEntity().WithPayload(cerrors.ErrPayloadFromSingleErr(principal, errors.New("cannot create db user with admin list name")))
	}

	existingUser, err := h.dbUsers.GetUsers(internalKey)
	if err != nil {
		return users.NewCreateUserInternalServerError().WithPayload(cerrors.ErrPayloadFromSingleErr(principal, fmt.Errorf("checking user existence: %w", err)))
	}

	if len(existingUser) > 0 {
		return users.NewCreateUserConflict().WithPayload(cerrors.ErrPayloadFromSingleErr(principal, fmt.Errorf("user '%v' already exists", params.UserID)))
	}

	apiKey, hash, userIdentifier, err := h.getApiKey()
	if err != nil {
		return users.NewCreateUserInternalServerError().WithPayload(cerrors.ErrPayloadFromSingleErr(principal, err))
	}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Choose a different userId that does not match the configured root user name and retry the create call.
2. Check the cluster config (AUTHENTICATION_APIKEY_USERS / root user settings) to see which names are reserved before provisioning users.
3. If you need admin capabilities for a new user, create it with an admin role assignment instead of reusing the root name.

Example fix

// before
POST /v1/users/db
{"userId": "root"}  // 422 cannot create db user with root user name

// after
POST /v1/users/db
{"userId": "app-service-user"}  // 201 created

const reserved = []string{"root"} // match configured root user name
if slices.Contains(reserved, params.UserID) { return errors.New("userId is reserved (root)") }

func isReservedUser(name, rootUserName string) bool { return name == rootUserName }

var uerr *users.CreateUserUnprocessableEntity
if err := createUser(userID); errors.As(err, &uerr) { log.Warnf("reserved name: %v", uerr.Payload.Error[0].Message) }

When it happens

Trigger: Calling POST /v1/users/db (or the users CreateUser REST endpoint) with body {"userId": "root"} (or whatever the configured root user name is) on a cluster with dynamic user management enabled.

Common situations: Scripts or provisioning automation that seed users from a list containing the built-in admin/root name; config migrations where the root user was renamed in AUTHENTICATION_APIKEY_USERS but the seed script still uses 'root'; test fixtures reusing 'root' as a sample username.

Related errors

• cannot create db user with admin list name
• a target namespace is required on namespace-enabled clusters
• namespaces are not enabled on this cluster; cannot import in
• the given class is empty
• one or more of the roles you want to assign is empty

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/b27a40196a2e6189. Report an issue: GitHub.