ipfs/kubo · error

error loading plugins: %s

Error message

error loading plugins: %s

What it means

Thrown by loadPlugins when constructing the plugin loader (loader.NewPluginLoader) fails. This typically means the repo path's plugin directory cannot be scanned or the loader cannot determine the repo's plugin configuration, so the daemon cannot start. The message wraps the underlying error from the loader constructor.

Source

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

	// for per-subsystem level control (e.g., `ipfs log level libp2p-swarm debug`).
	gologshim.SetDefaultHandler(logging.SlogHandler())
}

// declared as a var for testing purposes.
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
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Confirm IPFS_PATH is a valid, initialized repo: `ipfs repo version` or check that <IPFS_PATH>/config exists; run `ipfs init` if missing.
2. Fix permissions on <IPFS_PATH> and <IPFS_PATH>/plugins (`chown -R $(id -u):$(id -g) $IPFS_PATH`).
3. Read the wrapped underlying error in the message for the precise filesystem issue and address it.
4. If a broken plugin caused repo corruption, remove/reinstall the offending .so from the plugins dir or restore a clean repo.

Example fix

// before
IPFS_PATH=/nonexistent ipfs daemon  // loader cannot scan repo
// after
export IPFS_PATH=$HOME/.ipfs && ipfs init && ipfs daemon

repo := os.Getenv("IPFS_PATH")
if repo == "" {
	repo = "~/.ipfs"
}
if _, err := os.Stat(filepath.Join(repo, "config")); err != nil {
	log.Fatalf("%s is not an initialized kubo repo (missing config): run `ipfs init` first", repo)
}

When it happens

Trigger: Starting the daemon (or a code path preloading plugins) where NewPluginLoader(repoPath) fails: repo path invalid, unreadable <repo>/plugins directory, or corrupted plugin-related repo metadata.

Common situations: IPFS_PATH pointing at a non-existent or half-removed repo when launching the daemon; wrong permissions on the plugins dir after copying a repo between users; container images where the repo volume failed to mount.

Related errors

• error loading plugins (preload): %s
• error initializing plugins: %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/e15c4ae180ac46ef. Report an issue: GitHub.