{"record":{"id":"1738c382be1e7384","repo":"ipfs/kubo","slug":"cannot-specify-negative-offset","errorCode":null,"errorMessage":"cannot specify negative offset","messagePattern":"cannot specify negative offset","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/cat.go","lineNumber":47,"sourceCode":"\t},\n\n\tArguments: []cmds.Argument{\n\t\tcmds.StringArg(\"ipfs-path\", true, true, \"The path to the IPFS object(s) to be outputted.\").EnableStdin(),\n\t},\n\tOptions: []cmds.Option{\n\t\tcmds.Int64Option(offsetOptionName, \"o\", \"Byte offset to begin reading from.\"),\n\t\tcmds.Int64Option(lengthOptionName, \"l\", \"Maximum number of bytes to read.\"),\n\t\tcmds.BoolOption(progressOptionName, \"p\", \"Stream progress data. Defaults to true when stderr is a terminal.\"),\n\t},\n\tRun: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {\n\t\tapi, err := cmdenv.GetApi(env, req)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\toffset, _ := req.Options[offsetOptionName].(int64)\n\t\tif offset < 0 {\n\t\t\treturn errors.New(\"cannot specify negative offset\")\n\t\t}\n\n\t\tmax, found := req.Options[lengthOptionName].(int64)\n\n\t\tif max < 0 {\n\t\t\treturn errors.New(\"cannot specify negative length\")\n\t\t}\n\t\tif !found {\n\t\t\tmax = -1\n\t\t}\n\n\t\terr = req.ParseBodyArgs()\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\treaders, length, err := cat(req.Context, api, req.Arguments, int64(offset), int64(max))\n\t\tif err != nil {","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/cat.go#L29-L65","documentation":"`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.","triggerScenarios":"`ipfs cat <cid> --offset -5` or passing a negative value programmatically via the RPC API's offset option.","commonSituations":"Shell variable arithmetic producing negative offsets (e.g. `offset=$(($size - $n))` with n > size); scripts computing offsets from file sizes incorrectly.","solutions":["Clamp the computed offset to >= 0 before invoking: `[ $OFFSET -lt 0 ] && OFFSET=0`","If you intended to read the tail of the file, compute a positive offset equal to filesize - N","Validate user input at the script boundary before passing --offset"],"exampleFix":"// before\nOFFSET=$((SIZE - 100))  # can go negative\nipfs cat $CID --offset $OFFSET\n// after\n[ \"$OFFSET\" -lt 0 ] && OFFSET=0\nipfs cat $CID --offset $OFFSET","handlingStrategy":"validation","validationCode":"if offset < 0 {\n    return errors.New(\"offset must be >= 0\")\n}\n// then safe: ipfs cat cid --offset offset","typeGuard":"null","tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"negative offset\") {\n    // clamp offset to 0 and retry\n}","preventionTips":["Clamp computed offsets to >= 0 before invoking","Validate user-supplied numbers at script boundaries","Use shell arithmetic guards for size-derived offsets","Prefer positive offsets computed as filesize - N for tails"],"tags":["cli","cat","argument-validation"],"backgroundTag":"invalid-argument-range","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}