weaviate/weaviate · error

namespace %q has unknown state %q in snapshot

Error message

namespace %q has unknown state %q in snapshot

What it means

During snapshot restore, the namespaces controller validates every namespace in the snapshot payload. If a namespace's State field holds a value not recognized by isKnownState (not empty, not one of the known states like active), the restore is aborted before the in-memory namespace map is swapped in. This guards against restoring a snapshot produced by a newer/incompatible version or a corrupted snapshot.

Source

Thrown at usecases/namespaces/controller.go:416

	// A "null" snapshot decodes to a nil map; writing into it would panic.
	if restored == nil {
		restored = make(map[string]*cmd.Namespace)
	}
	for name, ns := range restored {
		if ns == nil {
			return fmt.Errorf("namespace %q in snapshot is null", name)
		}
		if len(ns.HomeNodes) != 1 || ns.HomeNodes[0] == "" {
			return fmt.Errorf("namespace %q in snapshot is missing home_node; "+
				"namespaces require a single home_node and have no migration path "+
				"from pre-home_node snapshots", name)
		}
		if ns.State == "" {
			ns.State = cmd.NamespaceStateActive
			continue
		}
		if !isKnownState(ns.State) {
			return fmt.Errorf("namespace %q has unknown state %q in snapshot", name, ns.State)
		}
	}

	c.mu.Lock()
	c.namespaces = restored
	c.mu.Unlock()

	c.logger.Info("successfully restored namespaces from snapshot")
	return nil
}

// ValidateName enforces the package's naming contract. It is the single
// source of truth for namespace name validation and is called both from the
// REST handler (for fast 422 rejection without a RAFT round-trip) and from
// the apply path (as a defense-in-depth check).
func ValidateName(name string) error {
	if err := entschema.ValidateNamespaceNameSyntax(name); err != nil {
		return err

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Check the State value(s) in the snapshot payload and correct or remove invalid entries
2. Restore using a snapshot produced by the same (or older) Weaviate version as the target
3. Upgrade the target node so it recognizes the new state before restoring
4. If the state is intentionally empty, remove the field or set it to "" so it is normalized to active

Example fix

// before (snapshot JSON)
{"name":"orders","state":"migrating"}
// after
{"name":"orders","state":"active"}

for _, ns := range snapshot.Namespaces {
    if ns.State != "" && !isKnownState(ns.State) {
        return fmt.Errorf("snapshot namespace %q has invalid state %q", ns.Name, ns.State)
    }
}

func hasKnownState(s string) bool { return s == "" || isKnownState(s) }

if err := c.Restore(snapshot); err != nil {
    if strings.Contains(err.Error(), "unknown state") {
        // snapshot version skew: inspect/upgrade before retrying
        return fmt.Errorf("snapshot incompatible: %w", err)
    }
    return err
}

When it happens

Trigger: Calling Controller.Restore with a snapshot containing a namespace whose State string is not a known state and not empty (which would be normalized to active).

Common situations: Restoring a snapshot from a newer Weaviate version that introduced new states; hand-edited or corrupted snapshot files; copying snapshot data across deployments with schema version skew.

Related errors

• restore roles: %w
• rewrite resource %q: %w
• backup references namespaces that are missing or deleting on
• namespace %q in snapshot is missing home_node; namespaces re
• there are no classes defined yet

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