ipfs/kubo · error

error initializing plugins: %s

Error message

error initializing plugins: %s

What it means

Thrown by loadPlugins when plugins.Initialize() fails — the phase that runs each discovered plugin's Init with plugin context/process info. A plugin returning an error from its Init (or crashing the init pass) aborts daemon startup. The plugin loader guarantees all plugins initialize or none proceed.

Source

Thrown at cmd/ipfs/kubo/start.go:90

	heapProfile        = "ipfs.memprof"
)

type PluginPreloader func(*loader.PluginLoader) error

func loadPlugins(repoPath string, preload PluginPreloader) (*loader.PluginLoader, error) {
	plugins, err := loader.NewPluginLoader(repoPath)
	if err != nil {
		return nil, fmt.Errorf("error loading plugins: %s", err)
	}

	if preload != nil {
		if err := preload(plugins); err != nil {
			return nil, fmt.Errorf("error loading plugins (preload): %s", err)
		}
	}

	if err := plugins.Initialize(); err != nil {
		return nil, fmt.Errorf("error initializing plugins: %s", err)
	}

	if err := plugins.Inject(); err != nil {
		return nil, fmt.Errorf("error initializing plugins: %s", err)
	}
	return plugins, nil
}

func printErr(err error) int {
	fmt.Fprintf(os.Stderr, "Error: %s\n", err.Error())
	return 1
}

func BuildDefaultEnv(ctx context.Context, req *cmds.Request) (cmds.Environment, error) {
	return BuildEnv(nil)(ctx, req)
}

// BuildEnv creates an environment to be used with the kubo CLI. Note: the plugin preloader should only call functions

View on GitHub (pinned to 329838acdf)

Solutions

1. Read the wrapped error to identify the failing plugin and remove it from <IPFS_PATH>/plugins, then restart.
2. Deduplicate: remove duplicate copies of the same plugin from the plugins directory.
3. Rebuild the plugin against the exact kubo/plugin API version of your binary; plugin .so files must match the kubo version they were built for.
4. Run with GOLOG_LOG_LEVEL=debug for a more precise failure point if the wrapped error is vague.

Example fix

// before
~/.ipfs/plugins/myplugin.so  built against kubo v0.20
// after
rebuild plugin against the current kubo version and replace the .so

// before daemon start, check for duplicate plugin files
seen := map[string]struct{}{}
entries, _ := os.ReadDir(filepath.Join(repoPath, "plugins"))
for _, e := range entries {
	if _, dup := seen[e.Name()]; dup {
		log.Fatalf("duplicate plugin %s in %s/plugins", e.Name(), repoPath)
	}
	seen[e.Name()] = struct{}{}
}

plugins, err := loadPlugins(repoPath, preload)
if err != nil && strings.Contains(err.Error(), "initializing plugins") {
	log.Printf("plugin Init failed: %v — remove the offending plugin from %s/plugins", err, repoPath)
	return err
}

When it happens

Trigger: Daemon startup with a plugin whose Init returns an error: duplicate plugin names, plugin type registration conflicts, or plugin code failing on its internal setup. Also triggered by corrupted/incompatible .so files that fail during initialization.

Common situations: Two copies of the same plugin in the plugins dir; a plugin compiled against a different kubo/plugin API version; plugins requiring environment (paths, files) not present in the container.

Related errors

• error loading plugins: %s
• error loading plugins (preload): %s
• serveHTTPGateway: GetConfig() failed: %s
• cannot create libp2p gateway: node PeerHost is nil (this sho
• ipfs api address could not be found

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