ipfs/kubo · error · ErrNotFile

this dag node is not a regular file

Error message

this dag node is not a regular file

What it means

`iface.ErrNotFile` is a sentinel error meaning the DAG node being accessed is not a regular UnixFS file. Unlike ErrIsDir (which specifically identifies directories), this covers other non-file node kinds — for example raw nodes, symlinks, or metadata nodes — for operations that require regular file content.

Source

Thrown at core/coreiface/errors.go:7

package iface

import "errors"

var (
	ErrIsDir        = errors.New("this dag node is a directory")
	ErrNotFile      = errors.New("this dag node is not a regular file")
	ErrOffline      = errors.New("this action must be run in online mode, try running 'ipfs daemon' first")
	ErrNotSupported = errors.New("operation not supported")
)

View on GitHub (pinned to 329838acdf)

Solutions

1. Verify the target's node type first (e.g. `ipfs dag get` or `ipfs files stat`) and use the appropriate API for that node kind.
2. If the node is a symlink, resolve the link target and request that path instead.
3. In code, check `errors.Is(err, iface.ErrNotFile)` and branch to a generic DAG reader (`api.Dag().Get`) instead of the UnixFS file reader.

Example fix

// before
f, err := api.Unixfs().Get(ctx, p) // fails on symlink
// after
node, err := api.Unixfs().Get(ctx, p)
if errors.Is(err, iface.ErrNotFile) {
    var ig pb.UnixFSData
    return inspectWithDagAPI(ctx, api, p) // generic dag handling
}

// Inspect the node before file operations:
out, err := api.Dag().Get(ctx, c) // then check unixfs data type (symlink, raw, etc.)

func isRegularFile(node files.Node) bool {
    _, ok := node.(files.File)
    return ok
}

node, err := api.Unixfs().Get(ctx, p)
if err != nil {
    if errors.Is(err, iface.ErrNotFile) {
        return readViaDagAPI(ctx, p) // symlink/raw node handling
    }
    return err
}

When it happens

Trigger: Invoking file-content operations (Unixfs Get/Cat with file expectations, or APIs that coerce the node to a files.File) on a CID/path that resolves to a non-regular-file node type (symlink, raw leaf, hamt-shard metadata, etc.).

Common situations: `ipfs cat` on a symlink node created via `ipfs files` with unixfs symlinks; attempting to read a shard/hamt internal node directly by CID; tooling that inspects DAG internals and hands internal node CIDs to file APIs.

Related errors

• this dag node is a directory
• unsupported file type '%s'
• file type %d not supported
• unknown layout: %d
• this action must be run in online mode, try running 'ipfs da

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