{"record":{"id":"215f7a96becd8ea6","repo":"ipfs/kubo","slug":"unexpected-links-len","errorCode":null,"errorMessage":"unexpected Links len","messagePattern":"unexpected Links len","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/rpc/unixfs.go","lineNumber":184,"sourceCode":"\tdefer resp.Close()\n\n\tdec := json.NewDecoder(resp.Output)\n\n\tfor {\n\t\tvar link lsOutput\n\t\tif err = dec.Decode(&link); err != nil {\n\t\t\tif err != io.EOF {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\treturn nil\n\t\t}\n\n\t\tif len(link.Objects) != 1 {\n\t\t\treturn errors.New(\"unexpected Objects len\")\n\t\t}\n\n\t\tif len(link.Objects[0].Links) != 1 {\n\t\t\treturn errors.New(\"unexpected Links len\")\n\t\t}\n\n\t\tl0 := link.Objects[0].Links[0]\n\n\t\tc, err := cid.Decode(l0.Hash)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tvar ftype iface.FileType\n\t\tswitch l0.Type {\n\t\tcase unixfs.TRaw, unixfs.TFile:\n\t\t\tftype = iface.TFile\n\t\tcase unixfs.THAMTShard, unixfs.TDirectory, unixfs.TMetadata:\n\t\t\tftype = iface.TDirectory\n\t\tcase unixfs.TSymlink:\n\t\t\tftype = iface.TSymlink\n\t\t}","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/client/rpc/unixfs.go#L166-L202","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the target path is a standard dag-pb UnixFS directory","Match daemon and client versions (the `ls` RPC response layout must agree)","Fall back to Dag().Get + manual IPLD traversal for exotic node types","If mocking the RPC in tests, mirror the real response shape: one Object with exactly one Link per entry"],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":null,"typeGuard":null,"tryCatchPattern":"entries, err := c.Unixfs().Ls(ctx, p)\nif err != nil {\n    if strings.Contains(err.Error(), \"Links len\") {\n        // fall back to dag traversal\n    }\n    return err\n}","preventionTips":["List only standard dag-pb directories","Don't hand-craft mocked ls responses that deviate from one Object/one Link per entry","Upgrade client and daemon together"],"tags":["rpc-client","unixfs","response-parsing"],"backgroundTag":"unexpected-response-shape","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}