ipfs/kubo · error

failed to initialize ephemeral node: %s

Error message

failed to initialize ephemeral node: %s

What it means

initTempNode fails with this when fsrepo.Init cannot initialize the ephemeral repo for the temp node; the created temp dir is removed and the underlying error is wrapped. Note the comment: repo plugins must already be loaded, otherwise init can fail.

Source

Thrown at repo/fsrepo/migrations/ipfsfetcher/ipfsfetcher.go:210

	// Disable listening for inbound connections
	cfg.Addresses.Gateway = []string{}
	cfg.Addresses.API = []string{}
	cfg.Addresses.Swarm = []string{tempNodeTCPAddr}

	if len(bootstrap) != 0 {
		cfg.Bootstrap = bootstrap
	}

	if len(peers) != 0 {
		cfg.Peering.Peers = peers
	}

	// Assumes that repo plugins are already loaded
	err = fsrepo.Init(dir, cfg)
	if err != nil {
		os.RemoveAll(dir)
		return "", fmt.Errorf("failed to initialize ephemeral node: %s", err)
	}

	return dir, nil
}

func (f *IpfsFetcher) startTempNode(ctx context.Context) error {
	// Open the repo
	r, err := fsrepo.Open(f.ipfsTmpDir)
	if err != nil {
		return err
	}

	// Create a new lifetime context that is used to stop the temp ipfs node
	ctxIpfsLife, cancel := context.WithCancel(context.Background())

	// Construct the node
	node, err := core.NewNode(ctxIpfsLife, &core.BuildCfg{
		Online:  true,

View on GitHub (pinned to 329838acdf)

Solutions

1. Ensure plugins are initialized (plugin loader run) before invoking IpfsFetcher/migrations
2. Read the wrapped %s error for the root cause (e.g. permissions, unsupported datastore) and fix that
3. Retry on a clean TMPDIR after removing stale ipfs-temp directories

Example fix

// before
fetcher, err := ipfsfetcher.NewIpfsFetcher(ctx, 0) // plugins not yet loaded
// after
if err := pluginloader.Initialize(); err != nil { return err }
fetcher, err := ipfsfetcher.NewIpfsFetcher(ctx, 0)

// plugins must be loaded before initializing the temp repo
if err := plugins.Init(os.TempDir()); err != nil { return err }

dir, err := initTempNode(ctx)
if err != nil && strings.HasPrefix(err.Error(), "failed to initialize ephemeral node") {
    // inspect wrapped cause; fix permissions/plugins, clear stale ipfs-temp dirs, retry
}

When it happens

Trigger: Repo plugins not loaded before starting the fetcher; invalid generated config for the temp node; permission problems writing into the temp dir; fsrepo lock issues.

Common situations: Running migrations in a stripped-down build where datastore/plugins are unavailable; concurrent migrations racing on fsrepo state; corrupted TMPDIR contents.

Related errors

• ipfs not initialized, please run 'ipfs init'
• reading repo config: %w
• repo is closed
• cannot access config, repo not open
• abort failed: close: %w, remove: %v

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