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

Pass a single regular file: `ipfs dag put file.json` or `cat data | ipfs dag put -`

expected a regular file

Error message

expected a regular file

What it means

`ipfs dag put` iterates req.Files entries and each must be a real file whose bytes it decodes with the codec chosen by --store-codec/--input-codec. If an entry is not a file (directory, symlink-ish entry, or missing handle), the command fails with "expected a regular file".

Source

Thrown at core/commands/dag/put.go:94

	if err != nil {
		return err
	}
	encoder, err := multicodec.LookupEncoder(uint64(scodec))
	if err != nil {
		return err
	}

	var adder ipld.NodeAdder = api.Dag()
	if dopin {
		adder = api.Dag().Pinning()
	}
	b := ipld.NewBatch(req.Context, adder)

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

		node := basicnode.Prototype.Any.NewBuilder()
		if err := decoder(node, file); err != nil {
			return err
		}
		n := node.Build()

		bd := bytes.NewBuffer([]byte{})
		if err := encoder(n, bd); err != nil {
			return err
		}

		blockCid, err := cidPrefix.Sum(bd.Bytes())
		if err != nil {
			return err
		}
		blk, err := blocks.NewBlockWithCid(bd.Bytes(), blockCid)

View on GitHub (pinned to 329838acdf)

Solutions

Pass a single regular file: `ipfs dag put file.json` or `cat data | ipfs dag put -`
Check the path is a file not a directory
Ensure the RPC client sends the payload as a file part

Example fix

// before
ipfs dag put ./data-dir
// error: expected a regular file
// after
ipfs dag put ./data-dir/obj.json

Defensive patterns

Strategy: validation

Validate before calling

// ensure input is a regular file before dag put
st, err := os.Stat(dataPath)
if err != nil {
    return err
}
if st.IsDir() {
    return fmt.Errorf("dag put requires a file; %s is a directory", dataPath)
}

Prevention

Use `ipfs add -r` for directories; dag put is per-file
When piping, verify the producer actually wrote data
Send file parts, not directory parts, in RPC multipart bodies

When it happens

Trigger: `ipfs dag put` given a directory path; piping nothing into `ipfs dag put -` so the stdin entry is not a file; RPC multipart with directory entries.

Common situations: Forgetting `ipfs add -r`-style recursion expectations — dag put does not walk directories; shell redirect mistakes producing empty stdin; API clients sending malformed multipart.

Related errors

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