What causes "paths must not be empty" in ipfs/kubo?

Ensure the path argument is non-empty before invoking the command (validate or default to "/").

paths must not be empty

Error message

paths must not be empty

What it means

checkPath in core/commands/files.go rejects any MFS path argument with length zero. The files commands operate on absolute paths within the mutable filesystem root, so an empty string can never name a node and is rejected before any lookup happens.

Source

Thrown at core/commands/files.go:1582

		fsn, err := pdir.Child(fname)
		if err != nil {
			return nil, err
		}

		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
	}

View on GitHub (pinned to 329838acdf)

Solutions

Ensure the path argument is non-empty before invoking the command (validate or default to "/").
Quote shell variables and check `[[ -n "$FILE" ]]` before calling `ipfs files`.
In API clients, validate arguments client-side before POSTing to /api/v0/files/*.

Example fix

// before
FILE=""
ipfs files stat "$FILE"   # paths must not be empty
// after
FILE="${FILE:-/}"
[[ -n "$FILE" ]] || { echo "path required"; exit 1; }
ipfs files stat "$FILE"

Defensive patterns

Strategy: validation

Validate before calling

[ -n "$P" ] || { echo "path required" >&2; exit 2; }

Type guard

func validPath(p string) bool { return len(p) > 0 }

Try / catch

cleaned, err := checkPath(p)
if err != nil {
    if strings.Contains(err.Error(), "must not be empty") { return fmt.Errorf("-p/--path is required") }
    return err
}

Prevention

Quote and default shell vars: "${FILE:-/}"
Validate CLI args before invoking `ipfs files *`
In API clients, reject empty `arg` fields client-side

When it happens

Trigger: Calling a files command (`files ls`, `files stat`, `files read`, `files rm`, ...) with an empty string as the path argument, e.g. an unset shell variable (`ipfs files stat "$FILE"` with FILE empty) or a script bug that drops the argument.

Common situations: Shell variables not quoted/initialized in automation; an API caller forwarding an empty `arg` to the /api/v0/files endpoint; a loop variable that came up empty.

Related errors

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