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

Pass a regular file, not a directory: ipfs block put ./data.bin

expected a file

Error message

expected a file

What it means

`ipfs block put` reads entries from the input files iterator and converts each to a files.File via files.FileFromEntry. A nil result means the entry is a directory or otherwise not a regular file, so it cannot be stored as a single block. The command fails fast for that entry.

Source

Thrown at core/commands/block.go:226

		cidCodec, _ := req.Options[blockCidCodecOptionName].(string)
		format, _ := req.Options[blockFormatOptionName].(string) // deprecated

		// use of legacy 'format' needs to suppress 'cid-codec'
		if format != "" {
			if cidCodec != "" && cidCodec != "raw" {
				return fmt.Errorf("unable to use %q (deprecated) and a custom %q at the same time", blockFormatOptionName, blockCidCodecOptionName)
			}
			cidCodec = "" // makes it no-op
		}

		pin, _ := req.Options[pinOptionName].(bool)

		it := req.Files.Entries()
		for it.Next() {
			file := files.FileFromEntry(it)
			if file == nil {
				return errors.New("expected a file")
			}

			p, err := api.Block().Put(req.Context, file,
				options.Block.Hash(mhtval, mhlen),
				options.Block.CidCodec(cidCodec),
				options.Block.Format(format),
				options.Block.Pin(pin))
			if err != nil {
				return err
			}

			if err := cmdutils.CheckBlockSize(req, uint64(p.Size())); err != nil {
				return err
			}

			err = res.Emit(&BlockStat{
				Key:  enc.Encode(p.Path().RootCid()),
				Size: p.Size(),

View on GitHub (pinned to 329838acdf)

Solutions

Pass a regular file, not a directory: ipfs block put ./data.bin
Use `ipfs add -r` instead if the input is a directory (produces a UnixFS DAG, not single blocks)
Filter directory entries out before feeding paths to block put in scripts

Example fix

// before
ipfs block put ./mydir
// after
ipfs block put ./mydir/file.bin   # or: ipfs add -r ./mydir

Defensive patterns

Strategy: validation

Validate before calling

// shell: only pass regular files to block put
for f in "$@"; do
  [ -f "$f" ] || { echo "not a regular file: $f" >&2; exit 1; }
done
ipfs block put "$@"

Prevention

Never pass directories to `ipfs block put`; use `ipfs add -r` for trees
Filter `find` output with -type f before feeding block put
Remember block put stores single blocks; directories need a UnixFS DAG

When it happens

Trigger: Run `ipfs block put ./somedir/` (a directory argument) — the iterator yields a directory entry, files.FileFromEntry returns nil, and the command errors with 'expected a file'.

Common situations: Passing a directory to block put by mistake (block put stores single blocks, unlike add); stdin/iterator entry that is not a regular file; scripts built for `ipfs add` reused for `ipfs block put`.

Related errors

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