What causes "error loading plugins (preload): %s" in ipfs/kubo?

Identify the failing plugin from the wrapped error and remove its binary from /plugins, then restart the daemon.

error loading plugins (preload): %s

Error message

error loading plugins (preload): %s

What it means

Thrown by loadPlugins when the optional PluginPreloader callback supplied to the daemon startup fails while warming up plugins (invoking their preload functions). The plugins loaded fine from disk, but exercising them ahead of node construction returned an error, so startup aborts. This usually surfaces a broken plugin implementation or a plugin that requires resources unavailable at preload time.

Source

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

var dnsResolver = madns.DefaultResolver

const (
	EnvEnableProfiling = "IPFS_PROF"
	cpuProfile         = "ipfs.cpuprof"
	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
}

View on GitHub (pinned to 329838acdf)

Solutions

Identify the failing plugin from the wrapped error and remove its binary from <IPFS_PATH>/plugins, then restart the daemon.
Fix the plugin's configuration or environment (missing config entries, files, or permissions) that its preload step depends on.
Rebuild against a known-good kubo/plugin version if the plugin is incompatible with the current loader API.

Example fix

// before
ls ~/.ipfs/plugins   # broken.so present, preload fails
// after
rm ~/.ipfs/plugins/broken.so && ipfs daemon

Defensive patterns

Strategy: try-catch

Try / catch

plugins, err := loadPlugins(repoPath, preload)
if err != nil {
	if strings.Contains(err.Error(), "preload") {
		log.Printf("plugin preload failed: %v — disable suspect plugins in %s/plugins and retry", err, repoPath)
		plugins, err = loadPlugins(repoPath, nil) // retry without preload hook
	}
	if err != nil {
		return err
	}
}

Prevention

Test custom plugins outside production before bundling them into the daemon
Keep plugin configuration and its external dependencies present at startup
Only wire preload hooks in controlled builds; document plugin prerequisites

When it happens

Trigger: Daemon start with a custom/plugin-enabled repo where a plugin's Preload (if implemented) returns an error — e.g. a plugin whose preload reads config or opens resources that fail. Only occurs when a preload hook is wired in (external/plugin builds or tests).

Common situations: Custom-built kubo with bundled plugins; third-party plugins under <IPFS_PATH>/plugins that fail during preload; misconfigured plugin dependencies (missing config keys, missing external binaries).

Related errors

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