ipfs/kubo · error

assets: could load Asset '%s': %s

Error message

assets: could load Asset '%s': %s

What it means

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.

Source

Thrown at assets/assets.go:45

}

// SeedInitDocs adds the list of embedded init documentation to the passed node, pins it and returns the root key.
func SeedInitDocs(nd *core.IpfsNode) (cid.Cid, error) {
	return addAssetList(nd, initDocPaths)
}

func addAssetList(nd *core.IpfsNode, l []string) (cid.Cid, error) {
	api, err := coreapi.NewCoreAPI(nd)
	if err != nil {
		return cid.Cid{}, err
	}

	dirMap := map[string]files.Node{}

	for _, p := range l {
		d, err := Asset.ReadFile(p)
		if err != nil {
			return cid.Cid{}, fmt.Errorf("assets: could load Asset '%s': %s", p, err)
		}

		dirMap[gopath.Base(p)] = files.NewBytesFile(d)
	}

	basePath, err := api.Unixfs().Add(nd.Context(), files.NewMapDirectory(dirMap))
	if err != nil {
		return cid.Cid{}, err
	}

	if err := api.Pin().Add(nd.Context(), basePath); err != nil {
		return cid.Cid{}, err
	}

	return basePath.RootCid(), nil
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Rebuild the ipfs binary from a clean checkout with the standard `make build` so go:embed assets are included
2. Verify the asset path passed to Asset.ReadFile exists in the embedded FS (check assets/assets.go embed directive and the list l)
3. If building a custom binary, ensure the assets/ directory contents are intact and committed before building
4. Replace the '%s' with '%w' in the fmt.Errorf so the underlying cause is chainable and debuggable

Example fix

// before
return cid.Cid{}, fmt.Errorf("assets: could load Asset '%s': %s", p, err)
// after
return cid.Cid{}, fmt.Errorf("assets: could load Asset '%s': %w", p, err)

// ensure binary integrity: assets are go:embed'ed, verify at startup
if _, err := assets.AssetFS.Open("path/to/asset"); err != nil {
    return fmt.Errorf("embedded assets missing, rebuild with `make build`: %w", err)
}

cid, err := assets.SeedInitDocs(ctx, api)
if err != nil {
    if strings.HasPrefix(err.Error(), "assets: could load Asset") {
        // embedded asset unreadable: rebuild binary from clean checkout
        return fmt.Errorf("corrupt build, rebuild: %w", err)
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• pin check failed: %w
• r.String()
• ipfs api address could not be found
• unexpected redirect
• unsupported file type '%s'

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