juicedata/juicefs · error

failed to get volume config %s: %v

Error message

failed to get volume config %s: %v

What it means

The `juicefs debug` command copies the volume's config file (`.config` or a prefixed variant) from the mount point directory into the output directory. This error is thrown by `collectSpecialFile` when `copyFile` fails, wrapping the underlying copy error (e.g. permission problems or a missing config file) with the config file name.

Source

Thrown at cmd/debug.go:478

		return fmt.Errorf("failed to write system info file %s: %v", sysPath, err)
	}

	fmt.Printf("\n%s\n", result)
	return nil
}

func collectSpecialFile(ctx *cli.Context, amp string, currDir string, requireRootPrivileges bool, wg *sync.WaitGroup) error {
	prefixed := true
	configName := ".jfs.config"
	_ = utils.WithTimeout(context.TODO(), func(context.Context) error {
		if !utils.Exists(filepath.Join(amp, configName)) {
			configName = ".config"
			prefixed = false
		}
		return nil
	}, 3*time.Second)
	if err := copyFile(filepath.Join(amp, configName), filepath.Join(currDir, "config.txt"), requireRootPrivileges); err != nil {
		return fmt.Errorf("failed to get volume config %s: %v", configName, err)
	}

	statsName := ".jfs.stats"
	if !prefixed {
		statsName = statsName[4:]
	}
	stats := ctx.Uint64("stats-sec")
	wg.Add(1)
	go func() {
		defer wg.Done()
		srcPath := filepath.Join(amp, statsName)
		destPath := filepath.Join(currDir, "stats.txt")
		if err := copyFile(srcPath, destPath, requireRootPrivileges); err != nil {
			logger.Errorf("Failed to get volume config %s: %v", statsName, err)
		}

		logger.Infof("Stats metrics are being sampled, sampling duration: %ds", stats)
		time.Sleep(time.Second * time.Duration(stats))

View on GitHub (pinned to c9a67b23e8)

Solutions

  1. Re-run `juicefs debug` with sudo/root so the config file can be read (the tool itself hints when root is needed).
  2. Verify the `.config` file exists at the mount point: `ls -la <mp>/.config`; if missing, the directory is not a JuiceFS mount — check the mount point.
  3. Check file permissions on `.config` and the output directory; ensure the output dir is writable.
  4. Inspect the wrapped `%v` error in the message to identify the exact copy failure (read vs write side).

Example fix

// before (run as normal user)
$ juicefs debug /jfs
// after (config file requires root to read)
$ sudo juicefs debug /jfs
Defensive patterns

Strategy: fallback

Validate before calling

if _, err := os.Stat(filepath.Join(mp, ".config")); err != nil { fmt.Println("not a JuiceFS mount point or config unreadable:", err) }
if os.Getuid() != 0 { fmt.Println("config may require root; consider sudo juicefs debug") }

Type guard

func hasVolumeConfig(mp string) bool { _, err := os.Stat(filepath.Join(mp, ".config")); return err == nil }

Try / catch

err := runDebug(mp)
var perr *fs.PathError
if errors.As(err, &perr) && errors.Is(perr.Err, os.ErrPermission) {
    // rerun with elevated privileges
}
return err

Prevention

When it happens

Trigger: Running `juicefs debug <mp>` where `copyFile(<mp>/.config, <out>/config.txt)` fails because the config file does not exist, the user lacks read permission, or the copy needs root (requireRootPrivileges) and the user is not root.

Common situations: Debugging a mount point owned by root while running as a normal user; the `.config` file was deleted from the mount point; the mount point is not actually a JuiceFS mount so `.config` is absent.

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

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