{"record":{"id":"b9878a1b84447bf7","repo":"hashicorp/packer","slug":"unrecognized-remote-plugin-message-s","errorCode":null,"errorMessage":"Unrecognized remote plugin message: %s","messagePattern":"Unrecognized remote plugin message: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packer/plugin_client.go","lineNumber":337,"sourceCode":"\tcase <-timeout:\n\t\terr = errors.New(\"timeout while waiting for plugin to start\")\n\tcase <-exitCh:\n\t\terr = errors.New(\"plugin exited before we could connect\")\n\tcase lineBytes := <-linesCh:\n\t\t// Trim the line and split by \"|\" in order to get the parts of\n\t\t// the output.\n\t\tline := strings.TrimSpace(string(lineBytes))\n\t\tparts := strings.SplitN(line, \"|\", 4)\n\t\tif len(parts) == 3 {\n\t\t\t// In protocol version 4 and before, the protocol only had a Major\n\t\t\t// version\n\t\t\terr = fmt.Errorf(\"The protocol of this plugin (protocol version 4 \" +\n\t\t\t\t\"and lower) was deprecated, please use a newer version of this plugin.\" +\n\t\t\t\t\"Or use an older version of Packer (pre 1.7) with this plugin.\")\n\t\t\treturn nil, err\n\t\t}\n\t\tif len(parts) < 4 {\n\t\t\terr = fmt.Errorf(\"Unrecognized remote plugin message: %s\", line)\n\t\t\treturn nil, err\n\t\t}\n\t\tpluginMajorAPIVersion, pluginMinorAPIVersion, network, netAddr := parts[0], parts[1], parts[2], parts[3]\n\n\t\t// Test the API versions\n\t\tif pluginMajorAPIVersion != pluginsdk.APIVersionMajor {\n\t\t\terr = fmt.Errorf(\"Incompatible API MAJOR version with plugin. \"+\n\t\t\t\t\"plugin MINOR API version: %s, Ours: %s\", pluginMajorAPIVersion, pluginsdk.APIVersionMajor)\n\t\t\treturn nil, err\n\t\t}\n\t\tif pluginMinorAPIVersion > pluginsdk.APIVersionMinor {\n\t\t\terr = fmt.Errorf(\"Incompatible API MINOR version with plugin. \"+\n\t\t\t\t\"plugin MINOR API version: %s, Ours: %s. Please upgrade Packer.\", pluginMinorAPIVersion, pluginsdk.APIVersionMinor)\n\t\t\treturn nil, err\n\t\t}\n\n\t\tswitch network {\n\t\tcase \"tcp\":","sourceCodeStart":319,"sourceCodeEnd":355,"githubUrl":"https://github.com/hashicorp/packer/blob/eb36e3c3e48a036f3e8cc94087636ee72e1303c9/packer/plugin_client.go#L319-L355","documentation":"The plugin client parses the plugin's handshake line, which must contain 4 pipe-separated fields (major version, minor version, network type, address). If the trimmed stdout line does not produce at least 4 fields, it is not a recognizable handshake, so Start fails with this error.","triggerScenarios":"Client.Start() in packer/plugin_client.go receives a first stdout line from the plugin process that is not a `major|minor|network|addr` handshake: the binary prints diagnostics, logs, an error message, or nothing meaningful instead of the handshake.","commonSituations":"Executed a binary that is not a Packer plugin at all (e.g. a script, a shell, a README accidentally marked executable); plugin crashes before handshake and prints a panic; plugin's stdout is polluted by print statements from custom code; wrong binary specified via required_plugins or PACKER_PLUGIN_PATH.","solutions":["Check that the configured binary path is actually a Packer plugin executable for the correct component type.","Run the plugin binary manually and inspect its stdout for panics or stray output.","Rebuild/reinstall the plugin from a clean, current packer-plugin-sdk version.","Remove any code in the plugin that writes non-handshake data to stdout (use stderr for logging)."],"exampleFix":"// before: plugin prints to stdout in main()\nfmt.Println(\"starting plugin...\") // pollutes handshake channel\n// after\nfmt.Fprintln(os.Stderr, \"starting plugin...\") // stderr is safe for logging","handlingStrategy":"validation","validationCode":"fi, _ := os.Stat(pluginPath)\nif fi != nil && fi.Mode().IsRegular() && fi.Mode().Perm()&0o111 != 0 {\n  // still verify it is a real plugin:\n  out, _ := exec.Command(pluginPath, \"packer-plugin\").Output()\n  isPlugin := strings.Count(strings.TrimSpace(string(out)), \"|\") >= 3\n}","typeGuard":null,"tryCatchPattern":"if _, err := client.Start(); err != nil {\n  if strings.Contains(err.Error(), \"Unrecognized remote plugin message\") {\n    log.Printf(\"%s is not a Packer plugin or crashed on startup: %v\", path, err)\n  }\n}","preventionTips":["Ensure the binary path points at a Packer plugin executable, not a script or doc.","Remove stdout prints from plugin code; log to stderr.","Rebuild plugins with the official packer-plugin-sdk.","Check for panics by running the plugin binary manually."],"tags":["plugin-protocol","handshake","plugin-binary"],"backgroundTag":"plugin-protocol-incompatible","analyzedSha":"eb36e3c3e48a036f3e8cc94087636ee72e1303c9","analyzedAt":"2026-09-05T13:20:43.127Z","contentChangedAt":"2026-09-05T13:20:43.127Z","schemaVersion":2},"datasetVersion":"2026-09-12T17:17:11.597Z"}