argoproj/argo-workflows · error

failed to look-up entrypoint/cmd for image %q, you must eith

Error message

failed to look-up entrypoint/cmd for image %q, you must either explicitly specify the command, or list the image's command in the index: https://argo-workflows.readthedocs.io/en/latest/workflow-executors/#emissary-emissary: %w

What it means

When building a workflow pod under the emissary executor, if a container specifies no command, the controller looks up the image's entrypoint/cmd in an index (docker hub or a configured registry index). This error means the lookup failed — either the index query errored or the image has no discoverable entrypoint — so the emissary pod cannot be constructed.

Source

Thrown at workflow/controller/workflowpod.go:762

			return nil, errors.Wrap(err, "", "Error applying PodSpecPatch")
		}
		pod.Spec = *patchedPodSpec
	}

	// In init-less mode the emissary binary is mounted at /argo-bin via the
	// argoexec-bin image volume, not copied to /var/run/argo by an init container.
	// K8s image volumes expose the image's root filesystem as-is.
	argoexecBinaryPath := pb.layout.argoexecBinaryPath()
	for i, c := range pod.Spec.Containers {
		if !common.IsArgoSidecar(c.Name) {
			// https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#notes
			if len(c.Command) == 0 {
				var x *entrypoint.Image
				x, err = pb.deps.lookupImage(ctx, c.Image, entrypoint.Options{
					Namespace: pb.in.namespace, ServiceAccountName: pb.in.execWfSpec.ServiceAccountName, ImagePullSecrets: pb.in.execWfSpec.ImagePullSecrets,
				})
				if err != nil {
					return nil, fmt.Errorf("failed to look-up entrypoint/cmd for image %q, you must either explicitly specify the command, or list the image's command in the index: https://argo-workflows.readthedocs.io/en/latest/workflow-executors/#emissary-emissary: %w", c.Image, err)
				}
				c.Command = x.Entrypoint
				if c.Args == nil { // check nil rather than length, as zero-length is valid args
					c.Args = x.Cmd
				}
			}
			execCmd := append(append([]string{argoexecBinaryPath, "emissary"}, pb.deps.getExecutorLogOpts(ctx)...), "--")
			c.Command = append(execCmd, c.Command...)
			// PER USER CONTAINER: for ContainerSet templates with N members the
			// init-less argoexec-bin mount and WAIT_FOR_READY must land on every
			// member, so this stays inside the per-container loop.
			pb.layout.decorateUserContainer(&c, hasAuxCtr)
		}
		if c.Image == pb.in.executorImage {
			// mount tmp dir to the executor container (wait, or supervisor in init-less mode)
			c.VolumeMounts = append(c.VolumeMounts, apiv1.VolumeMount{
				Name:      volumeTmpDir.Name,
				MountPath: "/tmp",

View on GitHub (pinned to 35bff19146)

Solutions

1. Explicitly set `command:` (and `args:`) on the container in the template so no lookup is needed
2. Verify the image exists and is pullable, and check the inner error for index/registry failures
3. Configure `containerRuntimeExecutor` index options / imagesPullSecrets or a custom entrypoint index for private registries
4. Add the image's command to a local index per the linked emissary docs

Example fix

// before
container:
  image: myrepo/distroless-tool
  args: ["--flag"]
// after
container:
  image: myrepo/distroless-tool
  command: ["/usr/bin/tool"]
  args: ["--flag"]

// in the Workflow template, always set command when the image may lack an ENTRYPOINT
// argo lint my-wf.yaml  # validate before submit

// controller-side
x, err := pb.deps.lookupImage(ctx, c.Image, opts)
if err != nil {
    return nil, fmt.Errorf("failed to look-up entrypoint/cmd for image %q ...: %w", c.Image, err)
}

When it happens

Trigger: A template container (or a container in a containerSet) omits `command` and entrypoint.LookupImage fails: image not found in the index, private registry auth failure, network error reaching the index, or the image genuinely declares no entrypoint.

Common situations: Scratch/distroless images with no ENTRYPOINT; private images not in the configured index; air-gapped clusters with no registry index access; typos in image names; switching executors to emissary where implicit entrypoint resolution is required.

Related errors

• failed to create ctr directory: %w
• failed to load system cert pool: %w

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