weaviate/weaviate · error

upgrade groupings: %w

Error message

upgrade groupings: %w

What it means

Restore detected a V0 snapshot and ran upgradeGroupingsFrom129 to migrate legacy grouping rows (using the authN config to resolve subjects); its error is wrapped as 'upgrade groupings'. This follows a successful policy upgrade, so the target is mid-migration when the failure occurs — retries of Restore are required to reach a consistent state.

Source

Thrown at usecases/auth/authorization/rbac/manager.go:724

	m.casbin.ClearPolicy()

	_, err := m.casbin.AddPolicies(snapshot.Policy)
	if err != nil {
		return fmt.Errorf("add policies: %w", err)
	}

	_, err = m.casbin.AddGroupingPolicies(snapshot.GroupingPolicy)
	if err != nil {
		return fmt.Errorf("add grouping policies: %w", err)
	}

	if snapshot.Version == SnapshotVersionV0 {
		if err := upgradePoliciesFrom129(m.casbin, true); err != nil {
			return fmt.Errorf("upgrade policies: %w", err)
		}

		if err := upgradeGroupingsFrom129(m.casbin, m.authNconf); err != nil {
			return fmt.Errorf("upgrade groupings: %w", err)
		}
	}

	// environment config needs to be applied again in case there were changes since the last snapshot
	if err := applyPredefinedRoles(m.casbin, m.rbacConf, m.authNconf, m.namespacesEnabled); err != nil {
		return fmt.Errorf("apply env config: %w", err)
	}

	// Load the policies to ensure they are in memory
	if err := m.casbin.LoadPolicy(); err != nil {
		return fmt.Errorf("load policies: %w", err)
	}

	// Invalidate the cache so the first Enforce() after the lock is released
	// evaluates against the freshly loaded policies. ClearPolicy() is not
	// overridden by SyncedCachedEnforcer and does not invalidate on its own.
	if err := m.casbin.InvalidateCache(); err != nil {
		return fmt.Errorf("restore snapshot: InvalidateCache: %w", err)

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Align the target's authentication configuration (AUTHENTICATION_* env) with the source cluster so legacy subjects can be resolved, then retry Restore.
2. Re-export the snapshot from a newer source version that writes SnapshotVersionLatest, avoiding the legacy groupings migration.
3. Inspect the wrapped error to find the un-upgradable g-row and clean up or recreate that assignment on the source.
4. Re-run Restore — the clear-then-add flow makes a full retry rebuild consistent state.

var probe struct{ Version int `json:"version"` }
if json.Unmarshal(b, &probe) == nil && probe.Version == 0 {
    // confirm target AUTHENTICATION config matches the snapshot's source cluster
}

if err := mgr.Restore(b, strip); err != nil {
    if strings.Contains(err.Error(), "upgrade groupings") {
        // align AUTHENTICATION_* env with source, then retry; or re-export from newer source
        alignAuthConfig();
        return mgr.Restore(b, strip)
    }
    return err
}

When it happens

Trigger: Restoring a V0 snapshot whose legacy g-rows cannot be rewritten against the current authN configuration: subject formats the 1.29->current migration does not recognize, missing/changed AUTHENTICATION config (e.g. OIDC settings) needed to re-derive subjects, or casbin write failures during the rewrite.

Common situations: Upgrading old clusters whose OIDC/static-key configuration differs between source and target; restoring old backups onto a cluster with different AUTHENTICATION env vars; snapshots containing subjects from auth providers no longer configured.

Related errors

• upgrade policies: %w
• user exists: %w
• username to assign role to doesn't exist
• oidc is not enabled
• no roles or users to restore: %w

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