containerd/containerd · error

failed to do idmap to get host ID: %w

Error message

failed to do idmap to get host ID: %w

What it means

With a valid spec and idmap, updateContainerIOOwner maps the container-namespace UID/GID (from spec.Process.User) to host IDs using userns.IDMap.ToHost. If the mapping cannot be performed (e.g. the container user has no corresponding host ID in the configured UID/GID mappings), this wrapped error is returned and the task is not started.

Source

Thrown at internal/cri/server/container_start_linux.go:68

	spec, err := cntr.Spec(ctx)
	if err != nil {
		return nil, fmt.Errorf("failed to get spec: %w", err)
	}

	if spec.Linux == nil || spec.Process == nil {
		return nil, fmt.Errorf("invalid linux platform oci runtime spec")
	}

	idMap := userns.IDMap{
		UidMap: spec.Linux.UIDMappings,
		GidMap: spec.Linux.GIDMappings,
	}
	hostID, err := idMap.ToHost(userns.User{
		Uid: spec.Process.User.UID,
		Gid: spec.Process.User.GID,
	})
	if err != nil {
		return nil, fmt.Errorf("failed to do idmap to get host ID: %w", err)
	}

	return []containerd.NewTaskOpts{
		containerd.WithUIDOwner(hostID.Uid),
		containerd.WithGIDOwner(hostID.Gid),
	}, nil
}

View on GitHub (pinned to 4246446a2b)

Solutions

1. Compare the container's UID/GID against the pod's UID/GID mappings and align them (adjust securityContext runAsUser or the mapping range)
2. Ensure /etc/subuid and /etc/subgid on the node cover the ranges assigned to user namespaces
3. Use runAsUser: 0 inside the userns container (mapped to an unprivileged host user)
4. Verify the userns range allocated by kubelet (user-namespaces feature) is large enough

Example fix

// before: image requires UID 100000 but pod userns range is 0-65535
// after: adjust securityContext to fit within the mapped range
spec:
  containers:
  - name: app
    securityContext:
      runAsUser: 1000   # inside the pod's userns mapping range
      runAsGroup: 1000

uid := securityContext.RunAsUser
gid := securityContext.RunAsGroup
if uid >= podUsernsRange.Size || gid >= podUsernsRange.Size {
    return fmt.Errorf("UID/GID %d/%d outside userns range size %d", uid, gid, podUsernsRange.Size)
}

if err := startContainer(id); err != nil {
    if strings.Contains(err.Error(), "failed to do idmap to get host ID") {
        // fix securityContext runAsUser/runAsGroup or /etc/subuid, /etc/subgid
    }
    return err
}

When it happens

Trigger: Starting a user-namespaced container whose spec.Process.User.UID/GID falls outside the ranges covered by spec.Linux.UIDMappings/GIDMappings, or when the mapping tables are empty/invalid.

Common situations: Container image or securityContext sets a UID (e.g. 100000) outside the pod's userns mapping range; kubelet userns range configuration doesn't cover the image's user; missing /etc/subuid//etc/subgid entries.

Related errors

• failed to get spec: %w
• unprivileged_icmp and unprivileged_port require kernel versi
• check current system kernel version error: %w
• path %q is mounted on %q but it is not a shared mount
• path %q is mounted on %q but it is not a shared or slave mou

AI-assisted analysis of containerd/containerd@4246446a2b (2026-09-02). Data as JSON: /api/errors/4057f9352d672f1f. Report an issue: GitHub.