ipfs/kubo · error

unexpected Links len

Error message

unexpected Links len

What it means

Same Ls decoding path: after confirming one Object, the client expects that Object to contain exactly one Link (the linked child). A mismatch means the RPC's returned object does not match the single-child dag-pb entry the client is trying to decode.

Source

Thrown at client/rpc/unixfs.go:184

	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:
			ftype = iface.TDirectory
		case unixfs.TSymlink:
			ftype = iface.TSymlink
		}

View on GitHub (pinned to 329838acdf)

Solutions

1. Ensure the target path is a standard dag-pb UnixFS directory
2. Match daemon and client versions (the `ls` RPC response layout must agree)
3. Fall back to Dag().Get + manual IPLD traversal for exotic node types
4. If mocking the RPC in tests, mirror the real response shape: one Object with exactly one Link per entry

entries, err := c.Unixfs().Ls(ctx, p)
if err != nil {
    if strings.Contains(err.Error(), "Links len") {
        // fall back to dag traversal
    }
    return err
}

When it happens

Trigger: The object returned for a link during Unixfs().Ls has zero or multiple Links — e.g. the path resolves to a node type the client's assumption doesn't hold for, or the daemon response format differs.

Common situations: Listing against an older/newer daemon with a changed `ls` output; listing non-directory or non-dag-pb nodes; corruption or manual construction of API responses in tests/mocks.

Related errors

• unexpected Objects len
• unsupported file type '%s'
• file type %d not supported
• unknowm mhType %d
• not a file node: %q

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