weaviate/weaviate · error

clean prior replica snapshot for op %q: %w

Error message

clean prior replica snapshot for op %q: %w

What it means

Wraps a failure from releaseReplicaSnapshot when cleaning a prior snapshot for the same opID. On retries of the same opID, a stale snapshot must be released before creating a fresh one; a failure here (e.g. staging-dir removal error) leaves stale state that would race the new snapshot.

Source

Thrown at adapters/repos/db/replica_snapshot.go:58

func (i *Index) IncomingCreateReplicaSnapshot(ctx context.Context, shardName, opID string) ([]string, error) {
	// Target retries can land twice server-side for the same opID; without
	// this lock they race on the staging dir.
	i.replicaSnapshotOpLocks.Lock(opID)
	defer i.replicaSnapshotOpLocks.Unlock(opID)

	shard, release, err := i.GetShard(ctx, shardName)
	if err != nil {
		return nil, fmt.Errorf("incoming create replica snapshot get shard %s: %w", shardName, err)
	}
	defer release()
	if shard == nil {
		return nil, fmt.Errorf("incoming create replica snapshot: shard %q not found", shardName)
	}

	// On retry the prior snapshot may be stale relative to current shard contents.
	if rerr := i.releaseReplicaSnapshot(ctx, opID, shard); rerr != nil {
		return nil, fmt.Errorf("clean prior replica snapshot for op %q: %w", opID, rerr)
	}

	stagingRoot := replicaStagingDir(i.Config.RootPath, opID, schema.ClassName(i.Config.ClassName))
	if err := os.MkdirAll(stagingRoot, 0o755); err != nil {
		return nil, fmt.Errorf("create replica staging dir: %w", err)
	}

	if file.ProbeHardlinkSupport(i.Config.RootPath) {
		files, err := shard.CreateReplicaSnapshot(ctx, stagingRoot)
		if err != nil {
			i.cleanupFailedReplicaSnapshot(stagingRoot, opID, false, nil)
			return nil, err
		}
		i.logger.WithField("op_id", opID).WithField("shard", shardName).
			Debugf("created replica snapshot: %d files", len(files))
		i.recordReplicaSnapshot(opID, replicaSnapshotState{shardName: shardName, isSnapshot: true})
		return files, nil
	}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Inspect the wrapped cause (disk permissions, staging dir in use) and clear the stale staging dir manually if needed.
2. Retry the operation once the prior snapshot state is cleaned; the opID lock serializes access.
3. If repeated, investigate leaked snapshot registrations in Index.replicaSnapshots.

When it happens

Trigger: Thrown at adapters/repos/db/replica_snapshot.go:58 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/e9b109b73d9c0a3f. Report an issue: GitHub.