What causes "File handler failed to create file %s" in dgraph-io/dgraph?

Ensure CreateDir was called (successfully) for the parent directory before CreateFile.

File handler failed to create file %s

Error message

File handler failed to create file %s

What it means

fileHandler.CreateFile wraps os.Create failures with 'File handler failed to create file <path>'. It means the local handler could not open the backup file for writing at the joined path — creation/permission/path problems, not write-time failures.

Source

Thrown at worker/backup_handler.go:210

}

type fileSyncer struct {
	fp *os.File
}

func (fs *fileSyncer) Write(p []byte) (n int, err error) { return fs.fp.Write(p) }
func (fs *fileSyncer) Close() error {
	if err := fs.fp.Sync(); err != nil {
		return errors.Wrapf(err, "while syncing file: %s", fs.fp.Name())
	}
	err := fs.fp.Close()
	return errors.Wrapf(err, "while closing file: %s", fs.fp.Name())
}

func (h *fileHandler) CreateFile(path string) (io.WriteCloser, error) {
	path = h.JoinPath(path)
	fp, err := os.Create(path)
	return &fileSyncer{fp}, errors.Wrapf(err, "File handler failed to create file %s", path)
}

func (h *fileHandler) Rename(src, dst string) error {
	src = h.JoinPath(src)
	dst = h.JoinPath(dst)
	return os.Rename(src, dst)
}

// pathExist checks if a path (file or dir) is found at target.
// Returns true if found, false otherwise.
func pathExist(path string) bool {
	_, err := os.Stat(path)
	if err == nil {
		return true
	}
	return !os.IsNotExist(err) && !os.IsPermission(err)
}

View on GitHub (pinned to 759e242be6)

Solutions

Ensure CreateDir was called (successfully) for the parent directory before CreateFile.
Check the wrapped os error's path/errno; fix permissions or remove the conflicting directory at that path.
Verify the file: URI rootDir and JoinPath result point where you expect (log the joined path).
Free disk space / fix read-only mounts if errno is ENOSPC or EROFS.

Example fix

// before
w, err := h.CreateFile(backupFile)
// after
if err := h.CreateDir(filepath.Dir(backupFile)); err != nil {
    return nil, err
}
w, err := h.CreateFile(backupFile)

Defensive patterns

Strategy: validation

Validate before calling

dir := filepath.Dir(backupPath)
if info, err := os.Stat(dir); err != nil || !info.IsDir() {
    return fmt.Errorf("parent dir %s missing/not a dir before CreateFile", dir)
}

Type guard

func dirWritable(dir string) bool {
    return unix.Access(dir, unix.W_OK) == nil
}

Try / catch

w, err := h.CreateFile(p)
if err != nil {
    var pe *os.PathError
    if errors.As(err, &pe) && errors.Is(pe.Err, syscall.ENOENT) {
        log.Printf("missing parent dir for %s — call CreateDir first", pe.Path)
    }
    return err
}

Prevention

Always pair CreateDir + CreateFile in a helper.
Validate the file: URI root at startup with a write test.
Keep backup file names within safe length/charset limits.
Run the worker as a user owning the backup root.

When it happens

Trigger: os.Create(JoinPath(path)) fails: parent directory doesn't exist (CreateDir was skipped or failed), EACCES, target name exists as a directory, ENOSPC on metadata, or invalid characters in the backup file name.

Common situations: Calling CreateFile without first calling CreateDir; wrong rootDir prefix in the file: URI; umask/permissions blocking the worker; a directory existing at the target file path; typo in the backup file name format.

Related errors

AI-assisted analysis of dgraph-io/dgraph@759e242be6 (2026-09-01). Data as JSON: /api/errors/99ff992fb12b0f55. Report an issue: GitHub.