argoproj/argo-workflows · error

failed to dial plugin %s at %q: %w

Error message

failed to dial plugin %s at %q: %w

What it means

grpc.NewClient failed to construct the gRPC client connection for the plugin's unix socket. This is a client-construction error (e.g. invalid target URL scheme or options), not a network failure — dialing is lazy in modern grpc-go.

Source

Thrown at workflow/artifacts/plugin/plugin.go:105

		"mode":       info.Mode(),
	}).Info(ctx, "plugin socket file exists and is a unix socket")

	conn, err := grpc.NewClient(
		"unix://"+socketPath,
		grpc.WithTransportCredentials(insecure.NewCredentials()),
		grpc.WithContextDialer(func(ctx context.Context, addr string) (net.Conn, error) {
			// Strip unix:// prefix if present
			if len(addr) > 7 && addr[:7] == "unix://" {
				addr = addr[7:]
			}
			dialer := &net.Dialer{Timeout: connectionTimeout}
			return dialer.DialContext(ctx, "unix", addr)
		}),
		// Add OpenTelemetry tracing for gRPC calls
		grpc.WithStatsHandler(otelgrpc.NewClientHandler()),
	)
	if err != nil {
		return nil, fmt.Errorf("failed to dial plugin %s at %q: %w", pluginName, socketPath, err)
	}

	driver := &Driver{
		pluginName: pluginName,
		conn:       conn,
		client:     artifact.NewArtifactServiceClient(conn),
	}

	// Verify the connection by checking the connection state
	ctx, cancel := context.WithTimeout(ctx, connectionTimeout)
	defer cancel()

	conn.Connect()

	// Wait for the connection to reach Ready state within the timeout
	for state := conn.GetState(); state != connectivity.Ready; state = conn.GetState() {
		if state == connectivity.Shutdown {
			_ = conn.Close()

View on GitHub (pinned to 35bff19146)

Solutions

1. Print/inspect the socketPath being passed to NewDriver; ensure it is an absolute filesystem path with no scheme prefix
2. Remove any 'unix://' prefix from the configured path — NewDriver adds it itself
3. Ensure socketPath is non-empty and a valid absolute POSIX path
4. If caused by dial options (e.g. credentials), check that no conflicting grpc options were introduced by a version upgrade

Example fix

// before
socketPath: "unix:///var/run/argo/plugins/myplug.sock"
// after
socketPath: "/var/run/argo/plugins/myplug.sock"

if socketPath == "" || !filepath.IsAbs(socketPath) || strings.Contains(socketPath, "://") {
    return fmt.Errorf("invalid plugin socketPath %q: must be an absolute path with no scheme", socketPath)
}

When it happens

Trigger: grpc.NewClient returns an error for the target "unix://<socketPath>" — typically a malformed target string (e.g. socketPath containing characters that break the unix:// URL, or an empty path) or invalid dial options.

Common situations: Empty or whitespace socketPath coming from plugin configuration, socketPath already containing a scheme prefix producing "unix://unix://...", or a misconfigured resolver target.

Related errors

• plugin %s connection shutdown (socket=%q)
• cannot use instance ID with Argo Server
• AuthSupplier cannot be empty when connecting to Argo Server
• plugin %s cannot stat unix socket at %q: %w
• plugin %s context cancelled while waiting for socket at %q:

AI-assisted analysis of argoproj/argo-workflows@35bff19146 (2026-09-03). Data as JSON: /api/errors/c13df3147f840dd1. Report an issue: GitHub.