derailed/k9s · warning

unable to locate container named %q

Error message

unable to locate container named %q

What it means

locateContainer searches po.Spec.Containers for the given name and found no match. The container name is not declared in the pod spec's main containers list, so specs like ports cannot be located. Init and ephemeral containers are excluded from this slice, which is the usual root cause.

Source

Thrown at internal/view/container.go:241

	}
	if cs == nil {
		return fmt.Errorf("unable to locate container status for %q", co)
	}

	if render.ToContainerState(cs.State) != "Running" {
		return fmt.Errorf("Container %s is not running?", co)
	}

	return nil
}

func locateContainer(co string, cc []v1.Container) (*v1.Container, error) {
	for i := range cc {
		if cc[i].Name == co {
			return &cc[i], nil
		}
	}
	return nil, fmt.Errorf("unable to locate container named %q", co)
}

func (c *Container) listForwardable(path string) (port.ContainerPortSpecs, map[string]string, bool) {
	po, err := fetchPod(c.App().factory, c.GetTable().Path)
	if err != nil {
		return nil, nil, false
	}

	co, err := locateContainer(path, po.Spec.Containers)
	if err != nil {
		c.App().Flash().Err(err)
		return nil, nil, false
	}

	if err := checkRunningStatus(path, po.Status.ContainerStatuses); err != nil {
		c.App().Flash().Err(err)
		return nil, nil, false
	}

View on GitHub (pinned to 2d3ccc6ba2)

Solutions

1. Use a name from Spec.Containers: kubectl get pod <pod> -o jsonpath='{.spec.containers[*].name}'.
2. If the target is an init/ephemeral container, extend the search to Spec.InitContainers / Spec.EphemeralContainers (note port-forward generally requires a running main container anyway).
3. Refresh the pod (watch/re-fetch) so the spec matches the live object before acting on it.
4. Check exact casing — matching is exact string equality.

Example fix

// before
co, err := locateContainer(path, po.Spec.Containers)

// after: fall back to init containers before failing
co, err := locateContainer(path, po.Spec.Containers)
if err != nil {
    co, err = locateContainer(path, po.Spec.InitContainers)
}

co, err := locateContainer(path, po.Spec.Containers)
if err != nil {
    if co, err = locateContainer(path, po.Spec.InitContainers); err != nil {
        return fmt.Errorf("container %q not in spec (main/init/ephemeral)", path)
    }
}

func containerInSpec(cc []v1.Container, name string) (*v1.Container, bool) {
    for i := range cc {
        if cc[i].Name == name { return &cc[i], true }
    }
    return nil, false
}

if err := locateContainer(path, po.Spec.Containers); err != nil {
    if strings.Contains(err.Error(), "unable to locate container named") {
    // re-fetch pod, verify name casing, and check init/ephemeral lists before giving up
    }
}

When it happens

Trigger: listForwardable (port-forward setup) or similar paths called with the name of an init container, ephemeral container, or a typo'd/mismatched name; a stale pod object from cache after the spec changed (containers renamed in a rollout); case-sensitive mismatch ('App' vs 'app').

Common situations: Port-forwarding to sidecars defined as init containers; debug ephemeral containers added post-creation; views holding cached pods across a deployment update; copy-paste of container names with wrong case.

Related errors

• unable to locate container status for %q
• Container %s is not running?
• user is not authorized to list pod metrics
• no exposed ports
• no port number assigned

AI-assisted analysis of derailed/k9s@2d3ccc6ba2 (2026-08-15). Data as JSON: /api/errors/fd4c2a48f2fed4f7. Report an issue: GitHub.