{"record":{"id":"d88b7389694e4511","repo":"ipfs/kubo","slug":"assets-could-load-asset-s-s","errorCode":null,"errorMessage":"assets: could load Asset '%s': %s","messagePattern":"assets: could load Asset '(.+?)': (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"assets/assets.go","lineNumber":45,"sourceCode":"}\n\n// SeedInitDocs adds the list of embedded init documentation to the passed node, pins it and returns the root key.\nfunc SeedInitDocs(nd *core.IpfsNode) (cid.Cid, error) {\n\treturn addAssetList(nd, initDocPaths)\n}\n\nfunc addAssetList(nd *core.IpfsNode, l []string) (cid.Cid, error) {\n\tapi, err := coreapi.NewCoreAPI(nd)\n\tif err != nil {\n\t\treturn cid.Cid{}, err\n\t}\n\n\tdirMap := map[string]files.Node{}\n\n\tfor _, p := range l {\n\t\td, err := Asset.ReadFile(p)\n\t\tif err != nil {\n\t\t\treturn cid.Cid{}, fmt.Errorf(\"assets: could load Asset '%s': %s\", p, err)\n\t\t}\n\n\t\tdirMap[gopath.Base(p)] = files.NewBytesFile(d)\n\t}\n\n\tbasePath, err := api.Unixfs().Add(nd.Context(), files.NewMapDirectory(dirMap))\n\tif err != nil {\n\t\treturn cid.Cid{}, err\n\t}\n\n\tif err := api.Pin().Add(nd.Context(), basePath); err != nil {\n\t\treturn cid.Cid{}, err\n\t}\n\n\treturn basePath.RootCid(), nil\n}\n","sourceCodeStart":27,"sourceCodeEnd":62,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/assets/assets.go#L27-L62","documentation":"This error comes from kubo's embedded-assets loader (addAssetList) when it reads a built-in asset file (e.g. the docs/init help files) from the go:embed FS and the read fails. Since the assets are compiled into the binary, this almost always indicates a build corruption or an unexpectedly empty/missing embedded FS rather than a user-level problem. It aborts the seed step of 'ipfs init', so no CID is produced.","triggerScenarios":"Calling SeedInitDocs (directly or via 'ipfs init') when Asset.ReadFile(p) fails for one of the embedded paths in the asset list; a broken or stripped build where the go:embed assets were not included; a misconfigured asset list pointing at a path that was not embedded.","commonSituations":"Custom/patched kubo builds where the assets directory was modified or removed; build tooling (e.g. UPX stripping or packaging scripts) corrupting the binary; running an old binary against a repo whose init flow expects new assets; writing Go code that calls SeedInitDocs with a custom asset list containing a non-embedded path.","solutions":["Rebuild the ipfs binary from a clean checkout with the standard `make build` so go:embed assets are included","Verify the asset path passed to Asset.ReadFile exists in the embedded FS (check assets/assets.go embed directive and the list l)","If building a custom binary, ensure the assets/ directory contents are intact and committed before building","Replace the '%s' with '%w' in the fmt.Errorf so the underlying cause is chainable and debuggable"],"exampleFix":"// before\nreturn cid.Cid{}, fmt.Errorf(\"assets: could load Asset '%s': %s\", p, err)\n// after\nreturn cid.Cid{}, fmt.Errorf(\"assets: could load Asset '%s': %w\", p, err)","handlingStrategy":"try-catch","validationCode":"// ensure binary integrity: assets are go:embed'ed, verify at startup\nif _, err := assets.AssetFS.Open(\"path/to/asset\"); err != nil {\n    return fmt.Errorf(\"embedded assets missing, rebuild with `make build`: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"cid, err := assets.SeedInitDocs(ctx, api)\nif err != nil {\n    if strings.HasPrefix(err.Error(), \"assets: could load Asset\") {\n        // embedded asset unreadable: rebuild binary from clean checkout\n        return fmt.Errorf(\"corrupt build, rebuild: %w\", err)\n    }\n    return err\n}","preventionTips":["Build kubo with the standard `make build`, never strip/corrupt the binary","Keep the assets/ directory intact in custom builds","Rebuild after rebasing onto releases that add new init assets"],"tags":["go","ipfs","embedded-assets","init"],"backgroundTag":"embedded-asset-load-failed","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"}