ipfs/kubo · error

error initializing plugins

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.

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
Defensive patterns

Strategy: try-catch

Validate before calling

// 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{}{}
}

Try / catch

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
}

Prevention

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

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

Appendix: 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)