{"record":{"id":"5b3da484a46bb29b","repo":"hashicorp/nomad","slug":"failed-to-launch-plugin-v","errorCode":null,"errorMessage":"failed to launch plugin: %v","messagePattern":"failed to launch plugin: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"helper/pluginutils/loader/loader.go","lineNumber":186,"sourceCode":"\tpinfo, ok := l.plugins[id]\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"unknown plugin with name %q and type %q\", name, pluginType)\n\t}\n\n\t// If the plugin is internal, launch via the factory\n\tvar instance PluginInstance\n\tif pinfo.factory != nil {\n\t\tctx, cancel := context.WithCancel(context.Background())\n\t\tinstance = &internalPluginInstance{\n\t\t\tinstance:   pinfo.factory(ctx, logger),\n\t\t\tapiVersion: pinfo.apiVersion,\n\t\t\tkillFn:     cancel,\n\t\t}\n\t} else {\n\t\tvar err error\n\t\tinstance, err = l.dispensePlugin(pinfo.baseInfo.Type, pinfo.apiVersion, pinfo.exePath, pinfo.args, nil, logger)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to launch plugin: %v\", err)\n\t\t}\n\t}\n\n\t// Cast to the base type and set the config\n\tb, ok := instance.Plugin().(base.BasePlugin)\n\tif !ok {\n\t\tinstance.Kill() // Ensure plugin is not left running\n\t\treturn nil, fmt.Errorf(\"plugin %s doesn't implement base plugin interface\", id)\n\t}\n\n\tc := &base.Config{\n\t\tPluginConfig: pinfo.msgpackConfig,\n\t\tAgentConfig:  config,\n\t\tApiVersion:   pinfo.apiVersion,\n\t}\n\n\tif err := b.SetConfig(c); err != nil {\n\t\tinstance.Kill() // ensure plugin is not left running","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/pluginutils/loader/loader.go#L168-L204","documentation":"For external plugins (no in-process factory), Dispense calls l.dispensePlugin to spawn the plugin binary via go-plugin and connect to it. Failures launching or handshaking with the subprocess are wrapped as \"failed to launch plugin\". The error detail comes from exec start, the go-plugin handshake, or RPC connection setup.","triggerScenarios":"Dispense of a plugin whose pinfo.factory is nil, when dispensePlugin fails: binary not executable, exec.Command start failure, handshake protocol mismatch, plugin exits immediately after launch, or stdout/stderr protocol corruption.","commonSituations":"Plugin binary rebuilt for a different architecture/OS; missing dynamic libraries or runtime (e.g. glibc version); plugin panics at startup; plugin_dir entry is a script without proper shebang; handshake config version mismatch between Nomad and plugin.","solutions":["Read the wrapped %v detail: exec vs handshake vs connection error point to different causes.","Run the plugin binary directly to confirm it executes and stays alive on this host.","Check the binary matches the host OS/architecture and has all runtime dependencies.","Verify the plugin's handshake API version is in Nomad's supported versions list.","Rebuild/reinstall the plugin from a matching Nomad plugin SDK release."],"exampleFix":"// before\n$ file plugin_dir/mydriver\nmydriver: ELF 64-bit LSB executable, x86-64   # on arm64 host\n// after\n$ GOARCH=arm64 go build -o plugin_dir/mydriver .","handlingStrategy":"try-catch","validationCode":"fi, err := os.Stat(exePath)\nif err != nil {\n    return fmt.Errorf(\"plugin binary missing: %s\", exePath)\n}\nif fi.Mode()&0111 == 0 {\n    return fmt.Errorf(\"plugin binary not executable: %s\", exePath)\n}","typeGuard":null,"tryCatchPattern":"inst, err := l.Dispense(name, ptype, agentCfg, logger)\nif err != nil && strings.Contains(err.Error(), \"failed to launch plugin\") {\n    // keep plugin stderr — go-plugin writes launch/handshake details there\n    return fmt.Errorf(\"plugin crashed at launch (see plugin stderr): %w\", err)\n}","preventionTips":["Smoke-test plugin binaries on the target OS/arch before deployment","Rebuild plugins when upgrading agent versions","Capture plugin stderr in logs — handshake errors are written there"],"tags":["plugin-loader","plugin-launch","process-spawn","nomad"],"backgroundTag":"plugin-launch-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}