juicedata/juicefs · error

failed to read config

Error message

failed to read config

What it means

Wraps an error from readConfig(mp) when `juicefs umount --flush` reads the JuiceFS volume config from the mount point. Unlike the ENOENT case (which reports 'not a JuiceFS mount point'), this fires for all other read failures — permission problems, I/O errors, or malformed mountpoint access.

Solutions

1. Read the full wrapped cause to identify the underlying errno (EACCES vs EIO vs ESTALE)
2. Check the mount is alive: `mountpoint <mp>` and `ls <mp>`; if hung, use `juicefs umount --force <mp>` (without --flush)
3. Retry with sufficient permissions (root/sudo) if it is an access error
4. If the FUSE connection is dead, force-unmount (`fusermount -uz <mp>`) and remount

Example fix

// before
juicefs umount /mnt/jfs --flush        # hangs / EIO, dead mount
// after
sudo umount -l /mnt/jfs                # or fusermount -uz /mnt/jfs, then remount
sudo juicefs umount /mnt/jfs --flush   # retry flush with proper permissions on healthy mount

if _, err := os.Stat(mp); err != nil { return fmt.Errorf("mountpoint missing: %w", err) }
if out, err := exec.Command("mountpoint", mp).CombinedOutput(); err != nil { return fmt.Errorf("not a mountpoint: %s", out) }

if err := umountCmd(mp, true); err != nil {
	var perr *fs.PathError
	if errors.As(err, &perr) && errors.Is(err, syscall.EIO) { /* dead mount: force unmount */ }
}

When it happens

Trigger: Running `juicefs umount <mp> --flush` where reading `.config` (or the config access path) inside the mountpoint fails with an error other than NotExist: no read permission on the mountpoint, stale/hung FUSE mount returning EIO/EACCES, network filesystem shadowing, or the mount process crashed leaving a broken mount.

Common situations: Unmounting a FUSE mountpoint whose juicefs process has died (mountpoint hangs, I/O errors); running as a user without permission to traverse the mountpoint; NFS/other fs mounted at the same path; dying metadata connection making any read on the mount fail.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• failed to parse config
• not a JuiceFS mount point
• build tls config from
• can not generate different endpoint using
• can't locate source or destination in command arguments

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

Appendix: source

Thrown at cmd/umount.go:109

		return fmt.Errorf("OS %s is not supported", runtime.GOOS)
	}
	out, err := cmd.CombinedOutput()
	if err != nil && len(out) != 0 {
		err = errors.New(string(out))
	}
	return err
}

func umount(ctx *cli.Context) error {
	setup(ctx, 1)
	mp := ctx.Args().Get(0)
	if ctx.Bool("flush") {
		raw, err := readConfig(mp)
		if err != nil {
			if os.IsNotExist(err) {
				return fmt.Errorf("not a JuiceFS mount point")
			}
			return errors.Wrap(err, "failed to read config")
		}

		var conf vfs.Config
		if err = json.Unmarshal(raw, &conf); err != nil {
			return errors.Wrap(err, "failed to parse config")
		}
		if conf.Chunk.Writeback {
			stagingDir := path.Join(conf.Chunk.CacheDir, "rawstaging")
			if err := waitWritebackComplete(stagingDir); err != nil {
				return err
			}
			defer func() {
				size, _ := fileSizeInDir(stagingDir)
				clearLastLine()
				if size == 0 {
					fmt.Println("\rAll staging chunks are flushed")
				} else {
					fmt.Printf("\r%s staging chunks are not flushed\n", humanize.IBytes(size))

View on GitHub (pinned to c9a67b23e8)