What causes "init: seeding init docs failed: %s" in ipfs/kubo?

Re-run `ipfs init` in a fresh IPFS_PATH to get a complete repo including the welcome docs.

init: seeding init docs failed: %s

Error message

init: seeding init docs failed: %s

What it means

Thrown by addDefaultAssets after a successful `ipfs init` when seeding the bundled welcome/init documents into the new repo (assets.SeedInitDocs) fails. The repo itself is initialized, but the sample docs and the printed 'to get started' root CID are missing. The wrapped value is the underlying error from the asset seeding path (blockservice/add of the embedded assets).

Source

Thrown at cmd/ipfs/kubo/init.go:223

func addDefaultAssets(out io.Writer, repoRoot string) error {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	r, err := fsrepo.Open(repoRoot)
	if err != nil { // NB: repo is owned by the node
		return err
	}

	nd, err := core.NewNode(ctx, &core.BuildCfg{Repo: r})
	if err != nil {
		return err
	}
	defer nd.Close()

	dkey, err := assets.SeedInitDocs(nd)
	if err != nil {
		return fmt.Errorf("init: seeding init docs failed: %s", err)
	}
	log.Debugf("init: seeded init docs %s", dkey)

	if _, err = fmt.Fprintf(out, "to get started, enter:\n"); err != nil {
		return err
	}

	_, err = fmt.Fprintf(out, "\n\tipfs cat /ipfs/%s/readme\n\n", dkey)
	return err
}

// pinEmptyDir pins the empty unixfs directory in the fresh repo.
//
// Until Kubo v0.43 this also published an IPNS record for the node's own
// key pointing at the empty directory. That record was never visible to
// the network (the DHT discarded records stored without a receive
// timestamp), and once the offline publish path started sharing the DHT's
// value store it would have been served to other peers, making a fresh

View on GitHub (pinned to 329838acdf)

Solutions

Re-run `ipfs init` in a fresh IPFS_PATH to get a complete repo including the welcome docs.
Inspect the wrapped error text for the real cause (disk full, datastore error) and fix that condition first.
If you do not need the sample docs, the repo is otherwise usable — proceed with `ipfs add`/`ipfs daemon` and ignore the missing docs.

Defensive patterns

Strategy: try-catch

Try / catch

err := runInit(out, ipfsPath) // wraps addDefaultAssets
if err != nil {
	if strings.Contains(err.Error(), "seeding init docs") {
		log.Printf("warning: repo initialized but welcome docs failed: %v — repo is usable", err)
		return nil // or re-init in a fresh path if docs are required
	}
	return err
}

Prevention

Ensure adequate free disk space before `ipfs init`
Avoid exotic or failing datastores on first init; test with default settings first
Treat the seeded docs as optional — a failure here does not invalidate the repo

When it happens

Trigger: SeedInitDocs returns an error: failure writing the asset blocks to the freshly created repo's datastore/datastore-internal errors, or an error constructing/opening the node used for seeding (the `nd.Close()` path indicates a node was opened).

Common situations: Corrupt or failing disk immediately after init; unusual datastore backends (e.g. badgerds profile) hitting write errors; out-of-disk/quota conditions; antivirus or filesystem interference deleting the repo mid-init.

Related errors

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