What causes "this dag node is a directory" in ipfs/kubo?

Use `ipfs ls ` (or `api.Unixfs().Ls`) instead of cat when the target is a directory.

ipfs/kubo · error · ErrIsDir

this dag node is a directory

Error message

this dag node is a directory

What it means

`iface.ErrIsDir` is a sentinel error in kubo's CoreAPI interface package indicating that the requested DAG node is a UnixFS directory rather than a regular file. Operations like `cat` can only stream file content, so when the resolved node is a directory the API refuses with this sentinel so callers can detect the case programmatically via errors.Is.

Source

Thrown at core/coreiface/errors.go:6

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

Use `ipfs ls <path>` (or `api.Unixfs().Ls`) instead of cat when the target is a directory.
Append the file name to the path to address a file inside the directory, e.g. `ipfs cat <dir-cid>/readme.md`.
In code, detect the case with `errors.Is(err, iface.ErrIsDir)` and switch to a directory-listing API.

Example fix

// before
r, err := api.Unixfs().Get(ctx, p)
// after
node, err := api.Unixfs().Get(ctx, p)
if errors.Is(err, iface.ErrIsDir) {
    dir, _ := mfs.NewDirectory(...) // or use api.Unixfs().Ls(ctx, p)
    return handleDirectory(dir)
}

Defensive patterns

Strategy: type-guard

Validate before calling

// Before cat, check the node kind:
stat, err := api.Unixfs().Ls(ctx, p)
// if Ls succeeds and entries exist, the path is a directory — use ls, not cat

Type guard

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

Try / catch

node, err := api.Unixfs().Get(ctx, p)
if err != nil {
    if errors.Is(err, iface.ErrIsDir) {
        return listDirectory(ctx, p) // switch to ls/Ls
    }
    return err
}

Prevention

Use `ipfs ls` to confirm the target is a file before `ipfs cat`
Address files inside directories explicitly: <dir-cid>/filename
Never assume a bare CID is a file; resolve the path fully first

When it happens

Trigger: Calling `api.Unixfs().Get`/`Cat` (or the `ipfs cat` CLI path) on a path/CID that resolves to a UnixFS directory node; in core/commands/cat.go the `files.Directory` case returns iface.ErrIsDir directly.

Common situations: Users running `ipfs cat <dir-cid>` on a directory root (very common — the CID points at a folder, not a file); scripts assuming a CID is a file; CID resolving to a directory after a path component was dropped or mistyped.

Related errors

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