{"record":{"id":"23e9c7f6968a87f3","repo":"ipfs/kubo","slug":"error-loading-plugins-preload-s","errorCode":null,"errorMessage":"error loading plugins (preload): %s","messagePattern":"error loading plugins \\(preload\\): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/ipfs/kubo/start.go","lineNumber":85,"sourceCode":"var dnsResolver = madns.DefaultResolver\n\nconst (\n\tEnvEnableProfiling = \"IPFS_PROF\"\n\tcpuProfile         = \"ipfs.cpuprof\"\n\theapProfile        = \"ipfs.memprof\"\n)\n\ntype PluginPreloader func(*loader.PluginLoader) error\n\nfunc loadPlugins(repoPath string, preload PluginPreloader) (*loader.PluginLoader, error) {\n\tplugins, err := loader.NewPluginLoader(repoPath)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error loading plugins: %s\", err)\n\t}\n\n\tif preload != nil {\n\t\tif err := preload(plugins); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"error loading plugins (preload): %s\", err)\n\t\t}\n\t}\n\n\tif err := plugins.Initialize(); err != nil {\n\t\treturn nil, fmt.Errorf(\"error initializing plugins: %s\", err)\n\t}\n\n\tif err := plugins.Inject(); err != nil {\n\t\treturn nil, fmt.Errorf(\"error initializing plugins: %s\", err)\n\t}\n\treturn plugins, nil\n}\n\nfunc printErr(err error) int {\n\tfmt.Fprintf(os.Stderr, \"Error: %s\\n\", err.Error())\n\treturn 1\n}\n","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/cmd/ipfs/kubo/start.go#L67-L103","documentation":"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.","triggerScenarios":"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).","commonSituations":"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).","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."],"exampleFix":"// before\nls ~/.ipfs/plugins   # broken.so present, preload fails\n// after\nrm ~/.ipfs/plugins/broken.so && ipfs daemon","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"plugins, err := loadPlugins(repoPath, preload)\nif err != nil {\n\tif strings.Contains(err.Error(), \"preload\") {\n\t\tlog.Printf(\"plugin preload failed: %v — disable suspect plugins in %s/plugins and retry\", err, repoPath)\n\t\tplugins, err = loadPlugins(repoPath, nil) // retry without preload hook\n\t}\n\tif err != nil {\n\t\treturn err\n\t}\n}","preventionTips":["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"],"tags":["plugins","daemon","startup"],"backgroundTag":"plugin-load-failed","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}