argoproj/argo-workflows · error

plugin %s expected unix socket at %q but it does not exist a

Error message

plugin %s expected unix socket at %q but it does not exist after waiting for %d seconds

What it means

NewDriver waits up to 120 seconds (1s poll interval) for the plugin's unix socket file to appear. If it never does, the driver gives up with this error, indicating the plugin process did not create its gRPC socket in time or at all.

Source

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

		logger.WithFields(logging.Fields{
			"pluginName": pluginName,
			"socketPath": socketPath,
			"retry":      retry,
			"maxRetries": maxRetries,
		}).Debug(ctx, "plugin socket not found, retrying in 1s")

		// Use context-aware sleep
		select {
		case <-time.After(time.Second):
			// Continue to next iteration
		case <-ctx.Done():
			return nil, fmt.Errorf("plugin %s context cancelled while waiting for socket at %q: %w", pluginName, socketPath, ctx.Err())
		}
	}

	// If socket still doesn't exist after all retries, fail with error
	if !socketExists {
		return nil, fmt.Errorf("plugin %s expected unix socket at %q but it does not exist after waiting for %d seconds", pluginName, socketPath, maxRetries)
	}

	if (info.Mode() & os.ModeSocket) == 0 {
		logger.WithFields(logging.Fields{
			"pluginName": pluginName,
			"socketPath": socketPath,
			"mode":       info.Mode(),
		}).Warn(ctx, "plugin socket file exists but is not a unix socket")
	}
	logger.WithFields(logging.Fields{
		"pluginName": pluginName,
		"socketPath": socketPath,
		"mode":       info.Mode(),
	}).Info(ctx, "plugin socket file exists and is a unix socket")

	conn, err := grpc.NewClient(
		"unix://"+socketPath,
		grpc.WithTransportCredentials(insecure.NewCredentials()),

View on GitHub (pinned to 35bff19146)

Solutions

1. Check the plugin pod's logs and restart count (kubectl logs / kubectl get pod) for startup crashes
2. Verify the socket path configured for the plugin matches the path the plugin binary actually listens on
3. Confirm the ArtifactPlugin resource / plugin configuration exists and points at a running plugin
4. Ensure both plugin and executor containers share the same volume where the socket is created
5. If the plugin genuinely needs >120s to start, fix startup latency (pre-pull images, faster init) — the wait is hard-coded

Example fix

// before: plugin listens on /tmp/other.sock, config says
socketPath: /var/run/argo/plugins/myplug.sock
// after: align plugin's listen path with config
socketPath: /var/run/argo/plugins/myplug.sock  # and plugin binds exactly this path

// proactively verify the plugin is deployed and healthy before artifact work
cli, _ := kube.NewForConfig(cfg)
pods, _ := cli.CoreV1().Pods(ns).List(ctx, metav1.ListOptions{LabelSelector: "app.kubernetes.io/name=<plugin>"})
if len(pods.Items) == 0 || !podRunning(pods.Items[0]) {
    return fmt.Errorf("plugin not running; refusing artifact operation")
}

if err != nil && strings.Contains(err.Error(), "does not exist after waiting") {
    // socket never appeared: alert on plugin deployment, don't blind-retry for another 120s
    return fmt.Errorf("plugin %s not deployed/healthy: %w", name, err)
}

When it happens

Trigger: The plugin container crashed on startup, is listening on a different socket path than configured, was never deployed (ArtifactPlugin CR / plugin config missing), or takes longer than 120s to bind.

Common situations: Plugin image misconfigured (wrong socket path env), plugin pod CrashLoopBackOff, plugin not installed in the namespace the workflow runs in, k3d/kind cluster where the socket volume isn't shared between plugin and executor containers.

Related errors

• plugin %s context cancelled while waiting for socket at %q:
• plugin %s cannot stat unix socket at %q: %w
• failed to dial plugin %s at %q: %w
• plugin %s connection shutdown (socket=%q)
• timeout waiting for plugin %s connection to become ready, la

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