juicedata/juicefs · error

object key %q escapes storage root %q

Error message

object key %q escapes storage root %q

What it means

Returned by filestore.path when resolving an object key inside the storage root would escape the root directory — the cleaned path's relation to the boundary starts with '..'. It is a path-traversal guard for file:// backed storage, so keys containing ../ sequences or absolute paths are rejected.

Source

Thrown at pkg/object/file.go:92

	return "file://" + d.root
}

func (d *filestore) path(key string) (string, error) {
	var p string
	if strings.HasSuffix(d.root, dirSuffix) {
		p = filepath.Join(d.root, key)
	} else {
		p = filepath.Clean(d.root + key)
	}

	boundary := d.root
	if !strings.HasSuffix(boundary, dirSuffix) {
		boundary = filepath.Dir(boundary)
	}

	rel, err := filepath.Rel(boundary, p)
	if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
		return "", fmt.Errorf("object key %q escapes storage root %q", key, d.root)
	}

	return p, nil
}

func (d *filestore) Head(ctx context.Context, key string) (Object, error) {
	p, err := d.path(key)
	if err != nil {
		return nil, err
	}
	fi, err := os.Lstat(p)
	if err != nil {
		return nil, err
	}
	isSymlink := fi.Mode()&os.ModeSymlink != 0
	if isSymlink {
		fi, err = os.Stat(p)
		if err != nil {

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Use object keys that stay inside the configured storage root
2. Sanitize keys that embed '..' or leading slashes before passing them to the file backend

When it happens

Trigger: Thrown at pkg/object/file.go:92 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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