What causes "%T is not a valid IPLD node" in ipfs/kubo?

Note the `%T` type name in the error and file a bugreport at https://github.com/ipfs/kubo/issues.

%T is not a valid IPLD node

Error message

%T is not a valid IPLD node

What it means

`ipfs dag get` resolves the requested path and expects the result object to implement `ipldlegacy.UniversalNode` so it can be narrowed to an `ipld.Node` for traversal/serialization. If the resolved value is some other type (an internal contract violation of the resolver/GetAPI), the command refuses with this error naming the unexpected Go type via `%T`.

Source

Thrown at core/commands/dag/get.go:51

	p, err := cmdutils.PathOrCidPath(req.Arguments[0])
	if err != nil {
		return err
	}

	rp, remainder, err := api.ResolvePath(req.Context, p)
	if err != nil {
		return err
	}

	obj, err := api.Dag().Get(req.Context, rp.RootCid())
	if err != nil {
		return err
	}

	universal, ok := obj.(ipldlegacy.UniversalNode)
	if !ok {
		return fmt.Errorf("%T is not a valid IPLD node", obj)
	}

	finalNode := universal.(ipld.Node)

	if len(remainder) > 0 {
		remainderPath := ipld.ParsePath(path.SegmentsToString(remainder...))

		finalNode, err = traversal.Get(finalNode, remainderPath)
		if err != nil {
			return err
		}
	}

	encoder, err := multicodec.LookupEncoder(uint64(codec))
	if err != nil {
		return fmt.Errorf("invalid encoding: %s - %s", codec, err)
	}

View on GitHub (pinned to 329838acdf)

Solutions

Note the `%T` type name in the error and file a bugreport at https://github.com/ipfs/kubo/issues.
Ensure CLI and daemon versions match and no patched boxo/coreapi is in use.
Try the same CID without a path suffix to see if plain node retrieval works.
Check `ipfs dag get --output-codec` / alternate codecs as a workaround while investigating.

Defensive patterns

Strategy: type-guard

Type guard

func asIPLDNode(v any) (ipld.Node, bool) {
    u, ok := v.(ipldlegacy.UniversalNode)
    if !ok {
        return nil, false
    }
    n, ok := u.(ipld.Node)
    return n, ok
}

Try / catch

if strings.HasSuffix(err.Error(), "is not a valid IPLD node") {
    // capture the %T type and report at github.com/ipfs/kubo/issues
}

Prevention

Keep kubo and boxo versions matched to avoid interface drift.
Test `ipfs dag get <cid>` without path suffixes when debugging exotic codecs.
Avoid patched coreapi/resolver code that could return non-node values.

When it happens

Trigger: Calling `ipfs dag get` (possibly with a path suffix/remainder) where the underlying API's `Get` returns a value that is not an IPLD node — e.g. an unexpected resolver output for the given codec, or a patched/mismatched coreapi layer.

Common situations: Requesting a CID/path whose codec resolves through a code path returning a non-node object; mixed kubo/boxo versions where the node interfaces changed; a bug in a custom resolver or plugin.

Related errors

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