ipfs/kubo · error

cannot have negative write offset

Error message

cannot have negative write offset

What it means

Guard in the `ipfs files write` handler: the --offset option was parsed as a negative int64 and is rejected before the destination file is opened or written. Pure input validation; a negative seek offset is not supported for MFS writes.

Source

Thrown at core/commands/files.go:1093

		rawLeaves, rawLeavesDef := req.Options[filesRawLeavesOptionName].(bool)

		if err := updateNoFlushCounter(nd, flush); err != nil {
			return err
		}

		if !rawLeavesDef && cfg.Import.UnixFSRawLeaves != config.Default {
			rawLeavesDef = true
			rawLeaves = cfg.Import.UnixFSRawLeaves.WithDefault(config.DefaultUnixFSRawLeaves)
		}

		prefix, err := getPrefix(req, &cfg.Import)
		if err != nil {
			return err
		}

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

		if mkParents {
			maxDirLinks := int(cfg.Import.UnixFSDirectoryMaxLinks.WithDefault(config.DefaultUnixFSDirectoryMaxLinks))
			sizeEstimationMode := cfg.Import.HAMTSizeEstimationMode()
			err := ensureContainingDirectoryExists(nd.FilesRoot, path,
				mfs.WithCidBuilder(prefix),
				mfs.WithMaxLinks(maxDirLinks),
				mfs.WithSizeEstimationMode(sizeEstimationMode),
			)
			if err != nil {
				return err
			}
		}

		fi, err := getFileHandle(nd.FilesRoot, path, create, prefix)
		if err != nil {
			return err

View on GitHub (pinned to 329838acdf)

Solutions

1. Use a non-negative --offset value.
2. If appending was intended, omit --offset or compute the file size with `ipfs files stat` instead of passing a negative value.

When it happens

Trigger: Thrown at core/commands/files.go:1093 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/8a92afa524a41950. Report an issue: GitHub.