weaviate/weaviate · error

a target namespace is required on namespace-enabled clusters

Error message

a target namespace is required on namespace-enabled clusters

What it means

On clusters with the namespaces (multi-namespace db users) feature enabled, every imported user must be assigned a target namespace. importUsers returns 422 when the namespace-enabled cluster receives an import request whose body has no namespace field.

Source

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

		if err := h.authorizer.Authorize(ctx, principal, authorization.CREATE, authorization.Users(wildcardKey)...); err != nil {
			return experimental.NewImportUsersForbidden().WithPayload(cerrors.ErrPayloadFromSingleErr(principal, err))
		}
	} else {
		keys := make([]string, 0, len(params.Body.Users))
		for _, rec := range params.Body.Users {
			keys = append(keys, apikey.MakeUserKey(bareUserID(rec), targetNamespace))
		}
		if err := h.authorizer.Authorize(ctx, principal, authorization.CREATE, authorization.Users(keys...)...); err != nil {
			return experimental.NewImportUsersForbidden().WithPayload(cerrors.ErrPayloadFromSingleErr(principal, err))
		}
		if err := h.authorizer.Authorize(ctx, principal, authorization.UPDATE, authorization.Users(keys...)...); err != nil {
			return experimental.NewImportUsersForbidden().WithPayload(cerrors.ErrPayloadFromSingleErr(principal, err))
		}
	}

	if h.namespacesEnabled {
		if targetNamespace == "" {
			return experimental.NewImportUsersUnprocessableEntity().WithPayload(cerrors.ErrPayloadFromSingleErr(principal, errors.New("a target namespace is required on namespace-enabled clusters")))
		}
	} else if targetNamespace != "" {
		return experimental.NewImportUsersUnprocessableEntity().WithPayload(cerrors.ErrPayloadFromSingleErr(principal, errors.New("namespaces are not enabled on this cluster; cannot import into a namespace")))
	}

	if len(params.Body.Users) == 0 {
		return experimental.NewImportUsersOK().WithPayload(&models.UserImportResponse{Results: []*models.UserImportResult{}})
	}

	// The apply re-checks the namespace; this only saves a round-trip per user
	// when this node already knows it is inactive.
	if err := namespaces.RequireActive(h.namespaces, targetNamespace); err != nil {
		return renderImportUsersNamespaceErr(principal, err)
	}

	response := &models.UserImportResponse{Results: make([]*models.UserImportResult, 0, len(params.Body.Users))}
	for _, rec := range params.Body.Users {
		response.Results = append(response.Results, h.importOneUser(ctx, targetNamespace, rec))

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Add a non-empty namespace to the import body: {"namespace": "<target>", "users": [...]}
2. List existing namespaces first and pick a valid one
3. If namespaces are not needed, disable AUTHENTICATION_DB_USERS_NAMESPACES_ENABLED so legacy imports are accepted
4. Update the migration tooling to require a namespace when the target cluster is namespace-enabled

Example fix

// before
{"users":[{"username":"alice","credentials":"..."}]}
// after
{"namespace":"team-a","users":[{"username":"alice","credentials":"..."}]}

if namespacesEnabled && (importReq.Namespace == "") {
  return errors.New("a target namespace is required on namespace-enabled clusters")
}

func importBodyValid(b *UserImportRequest, namespacesEnabled bool) bool {
  return b != nil && (!namespacesEnabled || b.Namespace != "")
}

if resp.StatusCode == 422 && strings.Contains(body, "target namespace is required") {
  return fmt.Errorf("add \"namespace\": \"<target>\" to the import body")
}

When it happens

Trigger: POST /v1/users/db/import with a valid body whose namespace is empty/omitted while h.namespacesEnabled is true (AUTHENTICATION_DB_USERS_NAMESPACES_ENABLED).

Common situations: Export files produced on a namespace-less cluster imported into a namespace-enabled cluster; clients written before namespaces existed; templates omitting the new namespace field after a version upgrade.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• namespaces are not enabled on this cluster; cannot import in
• a namespace-qualified user name "<namespace>:<user>" is requ
• cannot create db user with root user name
• cannot create db user with admin list name
• msg

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