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

Pass a real file or directory argument: ipfs add ./myfile

expected a file argument

Error message

expected a file argument

What it means

After iterating all input entries, the add command checks that at least one entry was actually processed (added > 0). If the iterator yielded nothing usable, there is nothing to add, so it errors. This is the guard for an empty or nonexistent input set.

Source

Thrown at core/commands/add.go:694

				}

				if err := res.Emit(&addEvent); err != nil {
					return err
				}
			}

			if err := <-errCh; err != nil {
				return err
			}
			added++
		}

		if addit.Err() != nil {
			return addit.Err()
		}

		if added == 0 {
			return fmt.Errorf("expected a file argument")
		}

		hasRoot := lastRootCid != path.ImmutablePath{}

		if fastProvideDAG && hasRoot {
			// DAG walk includes the root CID (DFS pre-order emits it
			// first), so a separate root provide is not needed.
			cmdenv.ExecuteFastProvideDAG(
				req.Context,
				ipfsNode.Context(),
				[]cid.Cid{lastRootCid.RootCid()},
				ipfsNode.ProvidingStrategy,
				ipfsNode.Blockstore,
				ipfsNode.Provider,
				fastProvideWait,
				uint(cfg.Provide.BloomFPRate.WithDefault(config.DefaultProvideBloomFPRate)),
				0, // block count unknown here; bloom chain auto-grows
			)

View on GitHub (pinned to 329838acdf)

Solutions

Pass a real file or directory argument: ipfs add ./myfile
Check the upstream pipeline actually emits bytes before piping into `ipfs add -`
Verify the file exists and is non-empty before invoking add in scripts

Example fix

// before
echo -n | ipfs add -
// after
test -s "$FILE" && ipfs add "$FILE" || echo "no input" >&2

Defensive patterns

Strategy: validation

Validate before calling

// verify input before ipfs add
if [ ! -s "$FILE" ]; then echo "empty or missing input: $FILE" >&2; exit 1; fi
ipfs add "$FILE"

Prevention

Check files are non-empty before piping into `ipfs add -`
Fail the pipeline early when an upstream step produces no output
In CI, assert the artifact to be added exists before the add step

When it happens

Trigger: Run `ipfs add` with stdin left empty (`ipfs add < /dev/null` or `echo -n | ipfs add -`); pass a file argument that resolves to zero entries; the added counter never increments because it.Next() returned no entries.

Common situations: Piping empty stdin into add in shell pipelines; a variable holding an empty path; CI scripts where the file to add was not produced by a prior step; reading from a FIFO that closed immediately.

Related errors

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