What causes "cannot specify negative length" in ipfs/kubo?

Compute remaining = total - offset and clamp to >= 0 before passing --length

cannot specify negative length

Error message

cannot specify negative length

What it means

`ipfs cat` accepts a `--length` option that must be non-negative; a negative value triggers `cannot specify negative length`. Note the check runs before the `found` test, so an explicitly provided negative length is rejected even though an absent length defaults internally to -1 (unlimited).

Source

Thrown at core/commands/cat.go:53

		cmds.Int64Option(offsetOptionName, "o", "Byte offset to begin reading from."),
		cmds.Int64Option(lengthOptionName, "l", "Maximum number of bytes to read."),
		cmds.BoolOption(progressOptionName, "p", "Stream progress data. Defaults to true when stderr is a terminal."),
	},
	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
		api, err := cmdenv.GetApi(env, req)
		if err != nil {
			return err
		}

		offset, _ := req.Options[offsetOptionName].(int64)
		if offset < 0 {
			return errors.New("cannot specify negative offset")
		}

		max, found := req.Options[lengthOptionName].(int64)

		if max < 0 {
			return errors.New("cannot specify negative length")
		}
		if !found {
			max = -1
		}

		err = req.ParseBodyArgs()
		if err != nil {
			return err
		}

		readers, length, err := cat(req.Context, api, req.Arguments, int64(offset), int64(max))
		if err != nil {
			return err
		}

		/*
			if err := corerepo.ConditionalGC(req.Context, node, length); err != nil {
				re.SetError(err, cmds.ErrNormal)

View on GitHub (pinned to 329838acdf)

Solutions

Compute remaining = total - offset and clamp to >= 0 before passing --length
Omit --length entirely to read to end of file (do not pass -1)
Validate numeric input before constructing the command

Example fix

// before
ipfs cat $CID --offset 5000 --length -1
// after
ipfs cat $CID --offset 5000   # reads to EOF

Defensive patterns

Strategy: validation

Validate before calling

if length != nil && *length < 0 {
    return errors.New("length must be >= 0; omit it to read to EOF")
}

Type guard

null

Try / catch

if err != nil && strings.Contains(err.Error(), "negative length") {
    // drop --length and retry to read to EOF
}

Prevention

Omit --length rather than passing sentinels like -1
Clamp remaining-bytes calculations to >= 0
Validate numeric options before building the command
Remember the internal -1 sentinel is not a valid CLI value

When it happens

Trigger: `ipfs cat <cid> --length -100` or an RPC call passing a negative length option.

Common situations: Scripts computing remaining bytes as `total - offset` where offset exceeds total; copying the internal sentinel -1 into the CLI where it is not accepted.

Related errors

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