ipfs/kubo · error

unexpected Objects len

Error message

unexpected Objects len

What it means

In the RPC client's Ls, each link coming back from the `ls` RPC is expected to carry exactly one Object wrapper (the dag-pb node holding the link). If len(link.Objects) != 1 the response shape doesn't match the dag-pb layout the client assumes, so it errors instead of decoding garbage.

Source

Thrown at client/rpc/unixfs.go:180

	}
	if resp.Error != nil {
		return err
	}
	defer resp.Close()

	dec := json.NewDecoder(resp.Output)

	for {
		var link lsOutput
		if err = dec.Decode(&link); err != nil {
			if err != io.EOF {
				return err
			}
			return nil
		}

		if len(link.Objects) != 1 {
			return errors.New("unexpected Objects len")
		}

		if len(link.Objects[0].Links) != 1 {
			return errors.New("unexpected Links len")
		}

		l0 := link.Objects[0].Links[0]

		c, err := cid.Decode(l0.Hash)
		if err != nil {
			return err
		}

		var ftype iface.FileType
		switch l0.Type {
		case unixfs.TRaw, unixfs.TFile:
			ftype = iface.TFile
		case unixfs.THAMTShard, unixfs.TDirectory, unixfs.TMetadata:

View on GitHub (pinned to 329838acdf)

Solutions

1. Point Ls at a dag-pb UnixFS directory path, not a raw/ipld node or a single file
2. Use the dag API (Dag().Get) or IPNS/path resolution to inspect non-dag-pb nodes instead of Unixfs().Ls
3. Re-add content with standard dag-pb settings (default `ipfs add` recipe) if you need unixfs listing semantics
4. Upgrade the client/daemon pair so both agree on the `ls` response shape

Example fix

// before
l, err := c.Unixfs().Ls(ctx, path.New("/ipfs/<raw-cid>"))
// after: list a dag-pb directory
l, err := c.Unixfs().Ls(ctx, path.New("/ipfs/<dag-pb-dir-cid>"))

// ensure target is a dag-pb unixfs directory before listing
nd, err := c.Dag().Get(ctx, p)
if err == nil && nd.Kind() != ipld.Kind_Map {
    return errors.New("path is not a unixfs directory")
}

entries, err := c.Unixfs().Ls(ctx, p)
if err != nil {
    if strings.Contains(err.Error(), "Objects len") {
        // fall back to Dag().Get traversal for non-dag-pb nodes
    }
    return err
}

When it happens

Trigger: Calling Unixfs().Ls on a path that resolves to a non-dag-pb UnixFS directory node (e.g. a raw or cbor node, or a CIDv1 raw block), so the RPC returns a link with zero or multiple Objects entries.

Common situations: Listing a directory added with raw-leaves/CIDv1 where entries are raw blocks; pointing Ls at a single file path instead of a directory; a daemon returning a different response layout than expected.

Related errors

• unexpected Links len
• %w: %v
• cannot add named links to a non-UnixFS dag-pb node; pass --a
• cannot add links to a HAMTShard at the dag-pb level (would c
• cannot add named links to a UnixFS %s node, only Directory n

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