What causes "expected a file argument" in ipfs/kubo?

Supply the required file argument(s) to the command or request

expected a file argument

Error message

expected a file argument

What it means

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.

Source

Thrown at core/commands/cmdenv/file.go:14

package cmdenv

import (
	"fmt"

	"github.com/ipfs/boxo/files"
)

// GetFileArg returns the next file from the directory or an error
func GetFileArg(it files.DirIterator) (files.File, error) {
	if !it.Next() {
		err := it.Err()
		if err == nil {
			err = fmt.Errorf("expected a file argument")
		}
		return nil, err
	}
	file := files.FileFromEntry(it)
	if file == nil {
		return nil, fmt.Errorf("file argument was nil")
	}
	return file, nil
}

View on GitHub (pinned to 329838acdf)

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

Example fix

// before
req.Files = nil
// after
req.Files = files.NewBytesFile([]byte("content"))

Defensive patterns

Strategy: validation

Validate before calling

if req.Files == nil {
    return errors.New("missing file argument")
}
// or before iterating:
// if !it.Next() { handle it.Err() or empty-input case }

Try / catch

file, err := cmdenv.GetFileArg(it)
if err != nil {
    if err.Error() == "expected a file argument" {
        return usageError("this command requires at least one file")
    }
    return err
}

Prevention

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

When it happens

Trigger: 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.

Common situations: `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.

Related errors

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