{"record":{"id":"44d9b5abd4a63dd6","repo":"ipfs/kubo","slug":"expected-a-file-argument-44d9b5","errorCode":null,"errorMessage":"expected a file argument","messagePattern":"expected a file argument","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/cmdenv/file.go","lineNumber":14,"sourceCode":"package cmdenv\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/ipfs/boxo/files\"\n)\n\n// GetFileArg returns the next file from the directory or an error\nfunc GetFileArg(it files.DirIterator) (files.File, error) {\n\tif !it.Next() {\n\t\terr := it.Err()\n\t\tif err == nil {\n\t\t\terr = fmt.Errorf(\"expected a file argument\")\n\t\t}\n\t\treturn nil, err\n\t}\n\tfile := files.FileFromEntry(it)\n\tif file == nil {\n\t\treturn nil, fmt.Errorf(\"file argument was nil\")\n\t}\n\treturn file, nil\n}\n","sourceCodeStart":1,"sourceCodeEnd":24,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/cmdenv/file.go#L1-L24","documentation":"GetFileArg iterates a files.Directory and returns the next file entry. When the iterator is exhausted (Next() returns false) and the iterator itself reports no error, the command lacked a file argument, so this generic error is returned. It indicates the command expected at least one file input but received none.","triggerScenarios":"Calling commands that consume file arguments (add, dag put, etc.) with an empty/missing file list, or iterating a directory that contains no entries; also surfaces when a DirIterator finishes unexpectedly in helper code.","commonSituations":"`ipfs add` invoked without stdin/file arg in scripts; RPC calls to add with an empty multipart body; test harnesses constructing cmds.Request without Files.","solutions":["Supply the required file argument(s) to the command or request","For stdin input, ensure stdin is piped and the command is invoked with the stdin flag","In tests, set req.Files to a non-empty files.NewBytesFile/Directory","Check the iterator's Err() separately if you call GetFileArg yourself — the real error is returned in place of this one"],"exampleFix":"// before\nreq.Files = nil\n// after\nreq.Files = files.NewBytesFile([]byte(\"content\"))","handlingStrategy":"validation","validationCode":"if req.Files == nil {\n    return errors.New(\"missing file argument\")\n}\n// or before iterating:\n// if !it.Next() { handle it.Err() or empty-input case }","typeGuard":null,"tryCatchPattern":"file, err := cmdenv.GetFileArg(it)\nif err != nil {\n    if err.Error() == \"expected a file argument\" {\n        return usageError(\"this command requires at least one file\")\n    }\n    return err\n}","preventionTips":["Always provide req.Files when invoking file-consuming commands","Pipe stdin explicitly in scripts that rely on stdin input","Mark command arguments as required in the command definition so the CLI rejects earlier"],"tags":["cli","files","arguments"],"backgroundTag":"missing-file-argument","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"}