What causes "unrecognized node type: %s" in ipfs/kubo?

Upgrade kubo to the latest version so it recognizes all current UnixFS node types

unrecognized node type: %s

Error message

unrecognized node type: %s

What it means

`ipfs files stat` encountered an MFS/UnixFS node whose type is not one of directory, HAMTShard, file, symlink, metadata, or raw. This error means the internal node kind returned by the node's Type() does not map to any supported stat output category, which normally indicates an unsupported or corrupt node type rather than user input error.

Source

Thrown at core/commands/files.go:416

	d, err := ft.FSNodeFromBytes(n.Data())
	if err != nil {
		return nil, err
	}

	stat := statOutput{
		Hash:           enc.Encode(cid),
		Blocks:         len(n.Links()),
		Size:           d.FileSize(),
		CumulativeSize: cumulsize,
	}

	switch d.Type() {
	case ft.TDirectory, ft.THAMTShard:
		stat.Type = "directory"
	case ft.TFile, ft.TSymlink, ft.TMetadata, ft.TRaw:
		stat.Type = "file"
	default:
		return nil, fmt.Errorf("unrecognized node type: %s", d.Type())
	}

	if mode := d.Mode(); mode != 0 {
		stat.Mode = uint32(mode)
	} else if d.Type() == ft.TSymlink {
		stat.Mode = uint32(os.ModeSymlink | 0x1FF)
	}

	if mt := d.ModTime(); !mt.IsZero() {
		stat.Mtime = mt.Unix()
		if ns := mt.Nanosecond(); ns > 0 {
			stat.MtimeNsecs = ns
		}
	}

	return &stat, nil
}

View on GitHub (pinned to 329838acdf)

Solutions

Upgrade kubo to the latest version so it recognizes all current UnixFS node types
Verify the path points to a normal file or directory created by `ipfs files`
Re-add or re-create the affected MFS entry, as the node data may be corrupted
Check the underlying block with `ipfs dag get <cid>` to inspect the actual node type

Defensive patterns

Strategy: validation

Validate before calling

// before stat, confirm the node is a known type
out, err := run("ipfs", "files", "ls", filepath.Dir(p))
if err != nil { return err }
if !strings.Contains(out, filepath.Base(p)) { return fmt.Errorf("path %s missing", p) }

Try / catch

if err := ipfsFilesStat(p); err != nil {
    if strings.Contains(err.Error(), "unrecognized node type") {
        // fall back to `ipfs dag get` to inspect the raw node, or upgrade kubo
    }
}

Prevention

Keep kubo up to date so all UnixFS node types are recognized
Only build MFS trees with `ipfs files add/cp/mkdir`, not hand-crafted DAGs
Pin and verify MFS roots after writes

When it happens

Trigger: Running `ipfs files stat <path>` where the node at the path has a UnixFS node type outside ft.TDirectory, ft.THAMTShard, ft.TFile, ft.TSymlink, ft.TMetadata, or ft.TRaw (e.g. a future/new UnixFS type produced by a newer node version, or a corrupted node).

Common situations: Reading an MFS entry written by a newer IPFS version with a node type this binary doesn't know; corrupted repo datastore entries; using stat on a path whose block data failed to parse into a known UnixFS type.

Related errors

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