What causes "file argument was nil" in ipfs/kubo?

Only pass file entries (or recurse into subdirectories yourself before calling GetFileArg)

file argument was nil

Error message

file argument was nil

What it means

After obtaining an entry from a DirIterator, GetFileArg converts it with files.FileFromEntry; if the entry is not a regular file (e.g. it is a subdirectory or a symlink to a dir), FileFromEntry returns nil and this error is returned. It means the next entry exists but is not usable as a file.

Source

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

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

Only pass file entries (or recurse into subdirectories yourself before calling GetFileArg)
Use the recursive option in add-style commands so directories are handled by the command
Filter the iterator: skip entries where files.FileFromEntry(it) == nil instead of erroring

Example fix

// before
file, err := cmdenv.GetFileArg(it)
// after
if it.Next() {
    if files.FileFromEntry(it) == nil {
        continue // skip directory/special entries
    }
    file, err := cmdenv.GetFileArg(it)

Defensive patterns

Strategy: validation

Validate before calling

if it.Next() && files.FileFromEntry(it) == nil {
    // entry is a directory/special node; recurse or skip before calling GetFileArg
}

Type guard

func isFileEntry(it files.DirIterator) bool {
    return files.FileFromEntry(it) != nil
}

Try / catch

file, err := cmdenv.GetFileArg(it)
if err != nil {
    if strings.Contains(err.Error(), "file argument was nil") {
        // skip or recurse into directory entry
    }
    return err
}

Prevention

Flatten or recurse into nested directories before consuming entries
Use recursive add modes for directory trees
Filter directory entries out of test inputs

When it happens

Trigger: Iterating a directory that contains subdirectories when the consumer expects only files (e.g. recursive add walking entries); a nil File result from files.FileFromEntry on directory entries.

Common situations: `ipfs add` on a directory needing recursive handling where the caller didn't descend into subdirs; constructing nested files.Directory inputs in tests; RPC multipart bodies containing directory entries.

Related errors

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