weaviate/weaviate · error

create parent folder for %s: %w

Error message

create parent folder for %s: %w

What it means

os.MkdirAll failed when creating the local parent directory that will hold the downloaded shard file. The copier recreates the shard's directory tree under the node's data path before writing the .tmp file.

Source

Thrown at cluster/replication/copier/copier.go:328

				return err
			}
		} else if checksum == meta.Crc32 {
			// local file matches remote one, no need to download it
			continue
		}

		stream, err := client.GetReplicaSnapshotFile(ctx, &protocol.GetReplicaSnapshotFileRequest{
			IndexName: meta.IndexName,
			OpId:      string(opID),
			FileName:  meta.FileName,
		})
		if err != nil {
			return fmt.Errorf("failed to send GetFile request for %s: %w", meta.FileName, err)
		}

		dir := path.Dir(localFilePath)
		if err := os.MkdirAll(dir, os.ModePerm); err != nil {
			return fmt.Errorf("create parent folder for %s: %w", localFilePath, err)
		}

		tmpPath := localFilePath + ".tmp"

		if err := func() error {
			f, err := os.Create(tmpPath)
			if err != nil {
				return fmt.Errorf("open file %q for writing: %w", tmpPath, err)
			}
			eg := enterrors.NewErrorGroupWrapper(c.logger)
			eg.SetLimit(_NUMCPU)
			// Drain writers before closing the FD: a late WriteAt against a
			// recycled descriptor would otherwise land on the wrong file.
			defer func() {
				_ = eg.Wait()
				if f != nil {
					_ = f.Close()
				}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Check the wrapped errno in the error: if EACCES, fix ownership/permissions of the data path (chown/chmod to the weaviate process user).
2. If ENOTDIR, remove the stray file occupying a directory component of the path.
3. If ENOSPC or EROFS, free disk space or remount the volume read-write.
4. Verify PERSISTENCE_DATA_PATH points to a writable, persistent volume in your deployment.

Example fix

// before: dir exists as a file, MkdirAll fails
$ ls /var/lib/weaviate
some-shard-dir   (regular file)
// after: remove the stray file so the directory tree can be created
$ rm /var/lib/weaviate/some-shard-dir && systemctl restart weaviate

dir := filepath.Join(dataPath, "")
if st, err := os.Stat(dir); err != nil {
    return fmt.Errorf("data path missing: %w", err)
} else if !st.IsDir() {
    return fmt.Errorf("data path is not a directory: %s", dir)
}
if err := syscall.Access(dir, os.O_RDWR); err != nil {
    return fmt.Errorf("data path not writable: %w", err)
}

When it happens

Trigger: MkdirAll on path.Dir(localFilePath) fails because the data directory's parent is missing/unwritable, a non-directory file exists at a path component, the disk is full or read-only, or permissions/ownership of the data dir are wrong (e.g. run as different user).

Common situations: PERSISTENCE_DATA_PATH mounted read-only or full; data dir owned by another user after a container image/user change; a stale file occupies a directory name (e.g. leftover from a torn migration); NFS/emptyDir volume issues in Kubernetes.

Related errors

• open file %q for writing: %w
• remove new segment file %q: %w
• failed to preallocate file: %w
• writing chunk to file %q: %w
• writing chunks to file %q: %w

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