juicedata/juicefs · error

failed to open file %s: %w

Error message

failed to open file %s: %w

What it means

`statBak` (used by `juicefs status`-style inspection of a backup via load's subcommands) opens the backup file with os.Open. If the open fails, the error is wrapped as `failed to open file <path>: <error>`. Unlike the stat error, this is raised at open time and reports the OS-level reason (ENOENT, EACCES, EISDIR, etc.).

Source

Thrown at cmd/load.go:263

			return err
		}
	}
	if format, err := m.Load(true); err == nil {
		if format.SecretKey == "removed" {
			logger.Warnf("secret key was removed; please correct it with `config` command")
		}
	} else {
		return err
	}
	logger.Infof("load metadata from %q succeed", src)
	return nil
}

func statBak(ctx *cli.Context, path string) error {
	logger.Infof("load backup from %q", path)
	fp, err := os.Open(path)
	if err != nil {
		return fmt.Errorf("failed to open file %s: %w", path, err)
	}
	defer fp.Close()

	if !ctx.IsSet("offset") {
		return showBakSummary(ctx, fp, false)
	}

	offset := ctx.Int64("offset")
	if offset == -1 {
		return showBakSummary(ctx, fp, true)
	}

	return showBakDetail(ctx, fp, offset)
}

func showBakSummary(ctx *cli.Context, fp *os.File, withOffset bool) error {
	bak := &meta.BakFormat{}
	footer, err := bak.ReadFooter(fp)

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Verify the path with `ls -l <path>`; fix typos and ensure it is a regular file
2. Check permissions (`sudo` if the backup was written by root)
3. Ensure the filesystem/volume holding the backup is mounted
4. Pass the correct backup file produced by `juicefs dump`/`load`

Example fix

// before
juicefs load --stat meta.sqlite3 /backups/
// after
juicefs load --stat meta.sqlite3 /backups/jfs-backup-20260906.json

fi, err := os.Stat(backupPath)
if err != nil { return err }
if fi.IsDir() { return fmt.Errorf("%s is a directory", backupPath) }
if err := unix.Access(backupPath, unix.R_OK); err != nil {
    return fmt.Errorf("%s not readable", backupPath)
}

if err := statBak(ctx, path); err != nil {
    if strings.Contains(err.Error(), "failed to open file") {
        var pe *fs.PathError
        log.Fatalf("open failed (ENOENT/EACCES?): %v", err)
    }
}

When it happens

Trigger: `juicefs load` backup-inspection path (statBak) invoked with a backup path that does not exist, is a directory, or is not readable by the current user.

Common situations: Typo'd backup filename; passing a directory instead of a file; file created by root but inspected as another user; backup on a detached/unmounted volume.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

• failed to create plain backup %s: %w
• name is required
• Could not get a FileSystem
• Cannot get file system.
• Cannot create file system.

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/dbc2c49f23bce278. Report an issue: GitHub.