weaviate/weaviate · error

create replica staging dir: %w

Error message

create replica staging dir: %w

What it means

Wraps the failure of creating the replica-snapshot staging directory (replicaStagingDir under rootPath) — typically a mkdir/permission/disk-space error — after the shard was successfully obtained and any prior snapshot cleaned.

Source

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

	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
	}

	// Halt-for-duration fallback: shard stays halted until Release; segments
	// are served from the live shard root in this mode. The inactivity timeout
	// backstops a target crash so the halt can't leak forever waiting on a peer that's gone.
	if err := shard.HaltForTransfer(ctx, false, i.Config.TransferInactivityTimeout); err != nil {

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Check disk space and permissions on the configured RootPath.
2. Inspect the wrapped OS error for the exact mkdir/read failure.
3. Free space or fix permissions, then retry the replication operation; the failed staging dir is cleaned up automatically.

When it happens

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