juicedata/juicefs · error

failed to parse config

Error message

failed to parse config

What it means

Wraps a json.Unmarshal failure when `juicefs umount --flush` parses the raw config bytes read from the mountpoint into vfs.Config. It means the bytes at the mountpoint config location are not valid JSON of the expected shape — effectively a corrupted or foreign config file.

Source

Thrown at cmd/umount.go:114

	}
	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))
				}
			}()
		}
	}
	return doUmount(mp, ctx.Bool("force"))

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Inspect the raw config content at the mountpoint (`cat <mp>/.config` or equivalent) to see what is actually there
2. Confirm the path is a JuiceFS mountpoint (`mount | grep <mp>`) and not another filesystem
3. Retry without --flush if writeback waiting is not needed (this parse only happens with --flush)
4. Upgrade/downgrade so the umount client version matches the mounting client version

Example fix

// before
juicefs umount /mnt/jfs --flush   # config not JSON -> parse error
// after
mount | grep /mnt/jfs             # verify it is a juicefs mount
juicefs umount /mnt/jfs           # unmount without flush, or fix/remount correctly

raw, err := readConfig(mp)
if err != nil { return err }
if !json.Valid(raw) { return fmt.Errorf("%s is not a JuiceFS config (invalid JSON)", mp) }

if err := umountCmd(mp, false); err != nil {
	if strings.Contains(err.Error(), "failed to parse config") {
		log.Printf("mountpoint config corrupt or foreign filesystem; retry without --flush")
	}
}

When it happens

Trigger: Running `juicefs umount <mp> --flush` where readConfig returns bytes that fail to parse: the mountpoint is not actually a JuiceFS mount (different file content at the config path), the config file was truncated/corrupted, or an incompatible JuiceFS version wrote a differently-shaped config.

Common situations: Path is a mountpoint of another filesystem whose config-like file is not JSON; manually edited or partially written config; version mismatch between client that wrote the format and client running umount.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• json: %s
• failed to unmarshal checkpoint: %w
• failed to read config
• invalid hour number
• invalid unit

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