ipfs/kubo · error

cannot specify negative offset

Error message

cannot specify negative offset

What it means

`ipfs cat` accepts an `--offset` option which must be non-negative. Before reading, the command casts the option to int64 and returns `cannot specify negative offset` if the value is below zero. Negative offsets have no meaning for reading a UnixFS file from the start.

Source

Thrown at core/commands/cat.go:47

	},

	Arguments: []cmds.Argument{
		cmds.StringArg("ipfs-path", true, true, "The path to the IPFS object(s) to be outputted.").EnableStdin(),
	},
	Options: []cmds.Option{
		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 {

View on GitHub (pinned to 329838acdf)

Solutions

1. Clamp the computed offset to >= 0 before invoking: `[ $OFFSET -lt 0 ] && OFFSET=0`
2. If you intended to read the tail of the file, compute a positive offset equal to filesize - N
3. Validate user input at the script boundary before passing --offset

Example fix

// before
OFFSET=$((SIZE - 100))  # can go negative
ipfs cat $CID --offset $OFFSET
// after
[ "$OFFSET" -lt 0 ] && OFFSET=0
ipfs cat $CID --offset $OFFSET

if offset < 0 {
    return errors.New("offset must be >= 0")
}
// then safe: ipfs cat cid --offset offset

null

if err != nil && strings.Contains(err.Error(), "negative offset") {
    // clamp offset to 0 and retry
}

When it happens

Trigger: `ipfs cat <cid> --offset -5` or passing a negative value programmatically via the RPC API's offset option.

Common situations: Shell variable arithmetic producing negative offsets (e.g. `offset=$(($size - $n))` with n > size); scripts computing offsets from file sizes incorrectly.

Related errors

• cannot specify negative length
• no bootstrap peers to add
• file does not support seeking
• expecting one argument: name
• a service name must be passed

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