{"record":{"id":"0e003f8ef01382ec","repo":"weaviate/weaviate","slug":"restore-roles-w","errorCode":null,"errorMessage":"restore roles: %w","messagePattern":"restore roles: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cluster/rbac/manager.go","lineNumber":322,"sourceCode":"// If this cluster uses namespaces, every namespace the roles name must exist\n// and not be deleting. Suspended and resuming namespaces are accepted because\n// they keep their rows, so restoring those rows is legal and must not block a\n// cluster-wide restore.\nfunc (m *Manager) ValidateBackupSnapshot(req *cmd.RestoreRolesAndUsersRequest, ns usecasesNamespaces.Exister) error {\n\tif m.authZ == nil || len(req.Roles) == 0 {\n\t\treturn nil\n\t}\n\tstaticAPIKeyUsers := rbac.StaticAPIKeyUsers(m.authNconfig)\n\tif err := rbac.ValidateSnapshot(req.Roles, req.StripNamespaces, staticAPIKeyUsers); err != nil {\n\t\treturn err\n\t}\n\tif req.StripNamespaces {\n\t\t// This cluster has namespaces turned off, so there is no namespace here\n\t\t// that could be active. The check above covers this case instead.\n\t\treturn nil\n\t}\n\tif err := rbac.RequireReferencedNamespacesExist(req.Roles, staticAPIKeyUsers, ns); err != nil {\n\t\treturn fmt.Errorf(\"restore roles: %w\", err)\n\t}\n\treturn nil\n}\n\n// RestoreFromBackup replaces every role with the ones from the backup.\n// Not to be confused with Restore, which loads roles when a node starts up.\nfunc (m *Manager) RestoreFromBackup(req *cmd.RestoreRolesAndUsersRequest) error {\n\tif m.authZ == nil || len(req.Roles) == 0 {\n\t\treturn nil\n\t}\n\tif err := m.authZ.Restore(req.Roles, req.StripNamespaces); err != nil {\n\t\t// The restore wipes the old roles before the part that can fail, so this\n\t\t// node may now have no custom roles at all while every other node\n\t\t// succeeded. Log a fixed word so this is easy to search for.\n\t\tm.logger.WithField(\"action\", \"restore_roles_from_backup\").\n\t\t\tErrorf(\"rbac_restore_torn: role store may be cleared on this node only: %v\", err)\n\t\treturn err\n\t}","sourceCodeStart":304,"sourceCodeEnd":340,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/cluster/rbac/manager.go#L304-L340","documentation":"ValidateBackupSnapshot verifies a backup's roles before a cluster-wide restore. When namespaces are enabled, RequireReferencedNamespacesExist checks that every namespace referenced by the backup's roles exists and is not being deleted; a failure is wrapped as \"restore roles: %w\". This is a pre-flight safety check so restoring roles never references namespaces that don't exist on this cluster.","triggerScenarios":"Restoring a backup whose roles reference namespaces that (a) don't exist on the target cluster, or (b) exist but are in the DELETING state. Suspended/resuming namespaces are accepted; active-deletion is not.","commonSituations":"Restoring a backup from cluster A into cluster B with a different namespace layout; attempting a restore while someone is concurrently deleting a namespace; operator disabled/renamed namespaces between backup and restore.","solutions":["Recreate (or stop deleting) the namespaces referenced by the backup's roles on the target cluster, then retry the restore","Inspect the backup's role list to find which namespaces are referenced and compare with the target cluster","Re-take the backup after aligning namespace configuration between source and target clusters"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// before restoring: confirm every namespace referenced by backup roles exists and is not deleting\nfor _, ns := range namespacesReferencedByBackupRoles(backup.Roles) {\n  if err := nsExister.Exists(ns); err != nil { return fmt.Errorf(\"namespace %s unavailable for restore\", ns) }\n}","typeGuard":null,"tryCatchPattern":"if err := manager.ValidateBackupSnapshot(req, nsExister); err != nil {\n  if strings.HasPrefix(err.Error(), \"restore roles:\") { /* reconcile namespaces then retry */ }\n}","preventionTips":["Align namespace configuration between source and target clusters before cross-cluster restores","Avoid deleting namespaces while a restore is in flight","Re-take backups after namespace topology changes"],"tags":["backup","restore","rbac","namespaces"],"backgroundTag":"backup-restore-namespace-missing","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"}