weaviate/weaviate · error

create temp class folder %s: %w

Error message

create temp class folder %s: %w

What it means

Wrap from writeTempFiles (usecases/backup/backend.go:949) when os.MkdirAll cannot create the class staging directory <tempDir>/<className> after the old one was removed. Without this directory, backup chunks cannot be unzipped into place, so the restore of the class fails.

Source

Thrown at usecases/backup/backend.go:949

	if fw.migrator != nil {
		if err := fw.migrator(classTempDir); err != nil {
			return fmt.Errorf("migrate from pre 1.23: %w", err)
		}
	}

	return nil
}

// writeTempFiles writes class files into a temporary directory
// temporary directory path = d.tempDir/className
// Function makes sure that created files will be removed in case of an error
func (fw *fileWriter) writeTempFiles(ctx context.Context, classTempDir, overrideBucket, overridePath string, desc *backup.ClassDescriptor, compressionType backup.CompressionType) (err error) {
	if err := os.RemoveAll(classTempDir); err != nil {
		return fmt.Errorf("remove %s: %w", classTempDir, err)
	}
	if err := os.MkdirAll(classTempDir, os.ModePerm); err != nil {
		return fmt.Errorf("create temp class folder %s: %w", classTempDir, err)
	}
	ctx, cancel := context.WithCancel(ctx)
	defer cancel()

	eg, ctx := enterrors.NewErrorGroupWithContextWrapper(fw.logger, ctx)
	eg.SetLimit(fw.GoPoolSize)
	for k := range desc.Chunks {
		// Check for cancellation before processing each chunk
		if err := ctx.Err(); err != nil {
			return err
		}
		chunk := chunkKey(desc.Name, k)
		eg.Go(func() error {
			return fw.readAndUnzipChunk(classTempDir, compressionType, chunk,
				func(w io.WriteCloser) error {
					_, err := fw.backend.Read(ctx, chunk, overrideBucket, overridePath, w)
					return err
				})

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Check the wrapped OS error and verify the parent directories of the configured data path exist and are writable by the Weaviate process user.
2. Confirm the persistence/data path configuration (PERSISTENCE_DATA_PATH) points to a valid writable volume.
3. Remove any regular file that occupies the temp directory path component.
4. If running in Kubernetes/Docker, fix the PVC/mount permissions and restart the node, then retry the restore.

Example fix

// before: PERSISTENCE_DATA_PATH points to unwritable dir
// WEAVIATE_PERSISTENCE_DATA_PATH=/nonexistent
// after: mount and point at a writable volume
// WEAVIATE_PERSISTENCE_DATA_PATH=/var/lib/weaviate

// preflight: parent of the temp dir must exist and be writable
parent := filepath.Dir(filepath.Join(dataPath, "backup-temp", className))
if fi, err := os.Stat(parent); err != nil || !fi.IsDir() {
    return fmt.Errorf("parent staging dir %s missing or not a directory", parent)
}
// also verify PERSISTENCE_DATA_PATH is writable at startup

func isMkdirFailure(err error) bool {
    return strings.Contains(err.Error(), "create temp class folder")
}

if err != nil && strings.Contains(err.Error(), "create temp class folder") {
    // EACCES/ENOENT on parent -> fix PERSISTENCE_DATA_PATH / permissions, retry
    log.Printf("cannot create staging dir: %v", err)
}

When it happens

Trigger: Restoring a class when the parent temp directory does not exist or cannot be created: missing parent path, read-only filesystem, ENOSPC is not typical here but EACCES/EEXIST-on-file are, or a file occupies a component of the path.

Common situations: Data path directory deleted while Weaviate runs; wrong persistence DATA_PATH configuration pointing at an unwritable location; a regular file named like the temp directory blocks creation; container user lacks write access to the mount.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• remove %s: %w
• read %s
• stat: %w
• create backup staging dir: %w
• stat shard dir: %w

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