{"record":{"id":"ee655815a65cee26","repo":"argoproj/argo-workflows","slug":"timeout-waiting-for-plugin-s-connection-to-become","errorCode":null,"errorMessage":"timeout waiting for plugin %s connection to become ready, last state: %s (socket=%q)","messagePattern":"timeout waiting for plugin (.+?) connection to become ready, last state: (.+?) \\(socket=%q\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"workflow/artifacts/plugin/plugin.go","lineNumber":130,"sourceCode":"\t}\n\n\t// Verify the connection by checking the connection state\n\tctx, cancel := context.WithTimeout(ctx, connectionTimeout)\n\tdefer cancel()\n\n\tconn.Connect()\n\n\t// Wait for the connection to reach Ready state within the timeout\n\tfor state := conn.GetState(); state != connectivity.Ready; state = conn.GetState() {\n\t\tif state == connectivity.Shutdown {\n\t\t\t_ = conn.Close()\n\t\t\treturn nil, fmt.Errorf(\"plugin %s connection shutdown (socket=%q)\", pluginName, socketPath)\n\t\t}\n\t\tif !conn.WaitForStateChange(ctx, state) {\n\t\t\t// Timeout or context cancelled\n\t\t\tcurrentState := conn.GetState()\n\t\t\t_ = conn.Close()\n\t\t\treturn nil, fmt.Errorf(\"timeout waiting for plugin %s connection to become ready, last state: %s (socket=%q)\", pluginName, currentState, socketPath)\n\t\t}\n\t}\n\n\tlogger.Info(ctx, fmt.Sprintf(\"plugin %s: connected successfully to %q\", pluginName, socketPath))\n\treturn driver, nil\n}\n\n// Close closes the gRPC connection\nfunc (d *Driver) Close() error {\n\tif d.conn != nil {\n\t\treturn d.conn.Close()\n\t}\n\treturn nil\n}\n\n// Load implements ArtifactDriver.Load by calling the plugin service\nfunc (d *Driver) Load(ctx context.Context, inputArtifact *wfv1.Artifact, path string) error {\n\tgrpcArtifact := convertToGRPC(inputArtifact)","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/argoproj/argo-workflows/blob/35bff19146f5a6ada77468c431f2624bd577e373/workflow/artifacts/plugin/plugin.go#L112-L148","documentation":"NewDriver gives the gRPC channel connectionTimeout to reach connectivity.Ready. WaitForStateChange returns false when the context deadline expires first; the driver then reports the last observed connectivity state. This is the standard 'plugin unreachable within timeout' failure.","triggerScenarios":"The socket file exists but the plugin is not accepting connections, the plugin is overloaded/hung, or connectionTimeoutSeconds is too small for the plugin to accept within it.","commonSituations":"Plugin process hung (deadlock) after binding the socket, socket backlog full, connectionTimeoutSeconds configured to a few seconds while the plugin takes longer to serve, plugin bound on a different network namespace (container isolation) so the executor can't reach the socket.","solutions":["Increase connectionTimeoutSeconds in the plugin configuration","Verify the plugin is accepting connections on the socket (grpcurl or plugin health check)","Check plugin logs/CPU for hangs or deadlocks; restart the plugin pod","Confirm plugin and executor containers share the volume mount and network namespace where the socket lives","Capture the reported last state in the message: TransientFailure vs Connecting points to refused connections vs slow startup respectively"],"exampleFix":"// before\nconnectionTimeoutSeconds: 5\n// after\nconnectionTimeoutSeconds: 60","handlingStrategy":"retry","validationCode":"// ensure a live listener exists and timeout is sane\nif conn, err := net.DialTimeout(\"unix\", socketPath, 2*time.Second); err != nil {\n    return fmt.Errorf(\"plugin not accepting connections on %s\", socketPath)\n} else { conn.Close() }\nif timeout < 10*time.Second { timeout = 30 * time.Second }","typeGuard":null,"tryCatchPattern":"if strings.Contains(err.Error(), \"timeout waiting for plugin\") {\n    // parse last state; retry once on Connecting/TransientFailure\n    return retryAfterDelay(5*time.Second, func() error {\n        var e error\n        drv, e = plugin.NewDriver(ctx, name, path, timeout)\n        return e\n    })\n}","preventionTips":["Set connectionTimeoutSeconds >= 30 for plugins with slow startup","Keep plugin health checks and restart policies aggressive so hung processes are recycled","Share the socket volume correctly between plugin and executor containers"],"tags":["grpc","timeout","connectivity","plugin-driver"],"backgroundTag":"grpc-ready-timeout","analyzedSha":"35bff19146f5a6ada77468c431f2624bd577e373","analyzedAt":"2026-09-03T19:34:35.908Z","contentChangedAt":"2026-09-03T19:34:35.908Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}