weaviate/weaviate · error

migrating sharding state from previous version

Error message

migrating sharding state from previous version

What it means

NewIndex detected a persisted sharding state file written by an older Weaviate version (pre-raft/no explicit physical state) and failed while migrating it forward. The collection's on-disk metadata cannot be upgraded in place, so index creation aborts rather than risking placement inconsistency.

Source

Thrown at adapters/repos/db/index.go:534

	index.replicator, err = replica.NewReplicator(cfg.ClassName.String(), router, nodeResolver, sg.NodeName(), getDeletionStrategy, replicaClient, promMetrics, logger)
	if err != nil {
		return nil, fmt.Errorf("create replicator for index %q: %w", index.ID(), err)
	}

	if cfg.AsyncReplicationScheduler == nil && cfg.ReplicationFactor > 1 {
		return nil, fmt.Errorf("init index %q: async replication scheduler is required when ReplicationFactor > 1", cfg.ClassName.String())
	}
	if globalReplicationConfig == nil && cfg.ReplicationFactor > 1 {
		return nil, fmt.Errorf("init index %q: global replication config is required when ReplicationFactor > 1", cfg.ClassName.String())
	}
	index.asyncReplicationScheduler = cfg.AsyncReplicationScheduler

	index.closingCtx, index.closingCancel = context.WithCancel(context.Background())

	index.initCycleCallbacks()

	if err := index.checkSingleShardMigration(); err != nil {
		return nil, errors.Wrap(err, "migrating sharding state from previous version")
	}

	if err := os.MkdirAll(index.path(), os.ModePerm); err != nil {
		return nil, fmt.Errorf("init index %q: %w", index.ID(), err)
	}

	// Remove the snapshots root to clean up any bucket snapshots left behind
	// by operations that were interrupted (e.g. server crash). This runs once
	// at index creation time — not on every shard load — so it won't interfere
	// with a snapshot that may be in use after a tenant re-activation.
	if err := os.RemoveAll(index.snapshotsPath()); err != nil {
		logger.WithField("action", "remove_orphaned_snapshots").
			WithField("path", index.snapshotsPath()).
			Error(err)
	}

	if err := index.initAndStoreShards(ctx, class, promMetrics); err != nil {
		return nil, err

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Follow the documented upgrade path: upgrade through the required intermediate Weaviate version before the current one
2. Backup the data directory before retrying, in case the migration partially ran
3. Inspect the wrapped cause; if the sharding state file is corrupt, restore from backup

When it happens

Trigger: Thrown at adapters/repos/db/index.go:534 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/bb4d7cf19cd27e4c. Report an issue: GitHub.