What causes "paths must start with a leading slash" in ipfs/kubo?

Prefix the argument with '/' if it does not already start with one.

paths must start with a leading slash

Error message

paths must start with a leading slash

What it means

checkPath in core/commands/files.go requires MFS paths to be absolute, i.e. start with '/'. MFS is rooted at '/', and commands like `files chchunk`/`files chmod` (and the shared path-check helper) reject relative or malformed paths with this error after cleaning is considered.

Source

Thrown at core/commands/files.go:1586

		fi, ok := fsn.(*mfs.File)
		if !ok {
			return nil, errors.New("expected *mfs.File, didn't get it. This is likely a race condition")
		}
		return fi, nil

	default:
		return nil, err
	}
}

func checkPath(p string) (string, error) {
	if len(p) == 0 {
		return "", fmt.Errorf("paths must not be empty")
	}

	if p[0] != '/' {
		return "", fmt.Errorf("paths must start with a leading slash")
	}

	cleaned := gopath.Clean(p)
	if p[len(p)-1] == '/' && p != "/" {
		cleaned += "/"
	}
	return cleaned, nil
}

func getParentDir(root *mfs.Root, dir string) (*mfs.Directory, error) {
	parent, err := mfs.Lookup(root, dir)
	if err != nil {
		return nil, err
	}

	pdir, ok := parent.(*mfs.Directory)
	if !ok {
		return nil, errors.New("expected *mfs.Directory, didn't get it. This is likely a race condition")

View on GitHub (pinned to 329838acdf)

Solutions

Prefix the argument with '/' if it does not already start with one.
Always pass absolute paths under the MFS root, e.g. `/dir/file.txt`.
Normalize/validate paths in scripts before calling the command (e.g. with `realpath -m` style logic, then prepend '/').

Example fix

// before
ipfs files ls dir/file.txt   # paths must start with a leading slash
// after
ipfs files ls /dir/file.txt

Defensive patterns

Strategy: validation

Validate before calling

case "$P" in /*) ;; *) P="/$P" ;; esac

Type guard

func isAbsolute(p string) bool { return strings.HasPrefix(p, "/") }

Try / catch

cleaned, err := checkPath(p)
if err != nil {
    if strings.Contains(err.Error(), "leading slash") { return fmt.Errorf("MFS paths must be absolute, got %q", p) }
    return err
}

Prevention

Always write MFS paths with a leading slash
Do not strip the leading slash when post-processing paths in scripts
Use one path-normalization helper across automation

When it happens

Trigger: Calling a files command with a relative path such as `dir/file.txt` instead of `/dir/file.txt`; passing a Windows-style path `C:\...`; a path built by string concatenation that lost its leading slash.

Common situations: Users treating MFS like the local filesystem (using relative paths from a working directory); scripts stripping the leading slash with cut/sed; API clients sending un-normalized paths.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/962006e50a6a3ad5. Report an issue: GitHub.