{"record":{"id":"1d4822bf0e66a5cc","repo":"weaviate/weaviate","slug":"namespace-q-has-unknown-state-q-in-snapshot","errorCode":null,"errorMessage":"namespace %q has unknown state %q in snapshot","messagePattern":"namespace %q has unknown state %q in snapshot","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"usecases/namespaces/controller.go","lineNumber":416,"sourceCode":"\t// A \"null\" snapshot decodes to a nil map; writing into it would panic.\n\tif restored == nil {\n\t\trestored = make(map[string]*cmd.Namespace)\n\t}\n\tfor name, ns := range restored {\n\t\tif ns == nil {\n\t\t\treturn fmt.Errorf(\"namespace %q in snapshot is null\", name)\n\t\t}\n\t\tif len(ns.HomeNodes) != 1 || ns.HomeNodes[0] == \"\" {\n\t\t\treturn fmt.Errorf(\"namespace %q in snapshot is missing home_node; \"+\n\t\t\t\t\"namespaces require a single home_node and have no migration path \"+\n\t\t\t\t\"from pre-home_node snapshots\", name)\n\t\t}\n\t\tif ns.State == \"\" {\n\t\t\tns.State = cmd.NamespaceStateActive\n\t\t\tcontinue\n\t\t}\n\t\tif !isKnownState(ns.State) {\n\t\t\treturn fmt.Errorf(\"namespace %q has unknown state %q in snapshot\", name, ns.State)\n\t\t}\n\t}\n\n\tc.mu.Lock()\n\tc.namespaces = restored\n\tc.mu.Unlock()\n\n\tc.logger.Info(\"successfully restored namespaces from snapshot\")\n\treturn nil\n}\n\n// ValidateName enforces the package's naming contract. It is the single\n// source of truth for namespace name validation and is called both from the\n// REST handler (for fast 422 rejection without a RAFT round-trip) and from\n// the apply path (as a defense-in-depth check).\nfunc ValidateName(name string) error {\n\tif err := entschema.ValidateNamespaceNameSyntax(name); err != nil {\n\t\treturn err","sourceCodeStart":398,"sourceCodeEnd":434,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/usecases/namespaces/controller.go#L398-L434","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check the State value(s) in the snapshot payload and correct or remove invalid entries","Restore using a snapshot produced by the same (or older) Weaviate version as the target","Upgrade the target node so it recognizes the new state before restoring","If the state is intentionally empty, remove the field or set it to \"\" so it is normalized to active"],"exampleFix":"// before (snapshot JSON)\n{\"name\":\"orders\",\"state\":\"migrating\"}\n// after\n{\"name\":\"orders\",\"state\":\"active\"}","handlingStrategy":"validation","validationCode":"for _, ns := range snapshot.Namespaces {\n    if ns.State != \"\" && !isKnownState(ns.State) {\n        return fmt.Errorf(\"snapshot namespace %q has invalid state %q\", ns.Name, ns.State)\n    }\n}","typeGuard":"func hasKnownState(s string) bool { return s == \"\" || isKnownState(s) }","tryCatchPattern":"if err := c.Restore(snapshot); err != nil {\n    if strings.Contains(err.Error(), \"unknown state\") {\n        // snapshot version skew: inspect/upgrade before retrying\n        return fmt.Errorf(\"snapshot incompatible: %w\", err)\n    }\n    return err\n}","preventionTips":["Only restore snapshots produced by the same Weaviate version","Never hand-edit snapshot files","Validate snapshot payloads before calling Restore","Pin and record the version that produced each snapshot"],"tags":["namespaces","snapshot","restore","state-validation"],"backgroundTag":"snapshot-unknown-state","analyzedSha":"75aa4b6d11f8818305aafd4440b4e32794f7ca04","analyzedAt":"2026-09-04T14:58:20.392Z","contentChangedAt":"2026-09-04T14:58:20.392Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}