ipfs/kubo · error

cannot specify negative offset

Error message

cannot specify negative offset

What it means

Fired by `ipfs files read` when the --offset option is explicitly negative. The option is read via a type assertion (a missing option defaults to 0), so this only triggers when the user supplied an offset below zero, which is meaningless for a seek-based read and is rejected before the file is read.

Source

Thrown at core/commands/files.go:863

		if err != nil {
			return fmt.Errorf("%s: %w", path, err)
		}

		fi, ok := fsn.(*mfs.File)
		if !ok {
			return fmt.Errorf("%s was not a file", path)
		}

		rfd, err := fi.Open(req.Context, mfs.Flags{Read: true})
		if err != nil {
			return err
		}

		defer rfd.Close()

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

		filen, err := rfd.Size()
		if err != nil {
			return err
		}

		if int64(offset) > filen {
			return fmt.Errorf("offset was past end of file (%d > %d)", offset, filen)
		}

		_, err = rfd.Seek(int64(offset), io.SeekStart)
		if err != nil {
			return err
		}

		var r io.Reader = &contextReaderWrapper{R: rfd, ctx: req.Context}
		count, found := req.Options[filesCountOptionName].(int64)

View on GitHub (pinned to 329838acdf)

Solutions

1. Pass a zero or positive --offset
2. Omit -o to read from the beginning of the file

When it happens

Trigger: Thrown at core/commands/files.go:863 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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