weaviate/weaviate · error

create requires a namespaced principal on a namespaces-enabl

Error message

create requires a namespaced principal on a namespaces-enabled cluster

What it means

Sentinel error returned by namespacing.QualifyForCreate when a global (or anonymous) principal attempts a create operation on a namespaces-enabled cluster. It fires during name qualification, before any storage happens: a principal without a namespace cannot have its resource names auto-prefixed, so the create is refused at the syntax/qualification layer rather than by the authz engine. Call sites (class and alias creation in usecases/schema) translate it into authzerrors.NewNamespaceForbidden, surfacing as a 403 to the client.

Source

Thrown at usecases/schema/namespacing/namespacing.go:32

// and to resolve them back. The helpers are pure syntax transforms except
// ResolveRoleName, which consults a caller-supplied existence callback to fall
// back from a namespace-local to a global role.
package namespacing

import (
	"errors"
	"fmt"
	"strings"

	"github.com/weaviate/weaviate/entities/models"
	"github.com/weaviate/weaviate/entities/schema"
)

// ErrCreateRequiresNamespace is returned by QualifyForCreate when a global
// (or anonymous) principal attempts a create on an NS-enabled cluster.
// Call sites translate this into authzerrors.NewNamespaceForbidden — the namespacing
// package stays free of auth vocabulary.
var ErrCreateRequiresNamespace = errors.New("create requires a namespaced principal on a namespaces-enabled cluster")

// ValidateNamespacePrefix rejects user-supplied class/alias names whose
// "<namespace>:" prefix is malformed. Returns nil when name has no separator.
// kind is the noun ("class" or "alias") used in the generic error message so
// the wording matches the field the caller is validating.
//
// The error wording depends on the caller's context so namespaces stay
// invisible to principals who shouldn't know about them:
//
//   - Namespaced principal, or NS-disabled cluster: returns a generic
//     "is not a valid <kind> name" error — namespaced users should never
//     send qualified names (the resolver adds their prefix automatically),
//     and on NS-disabled clusters namespaces simply don't exist as a
//     concept.
//   - Global principal on NS-enabled cluster: returns the specific
//     "invalid namespace prefix" error — these are the operators who
//     legitimately type qualified names and benefit from an actionable
//     message about which part is wrong.

View on GitHub (pinned to 75aa4b6d11)

Solutions

  1. Run the create as a principal that belongs to a namespace (namespaced API key or user) so names can be qualified
  2. Assign the global principal a namespaced scope or perform the create through an admin confined to the target namespace
  3. Disable namespaces on the cluster if global principals must create resources
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at usecases/schema/namespacing/namespacing.go:32 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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