{"record":{"id":"30b37f0d3e7dc8b0","repo":"containerd/containerd","slug":"user-namespace-configuration-w-30b37f","errorCode":null,"errorMessage":"user namespace configuration: %w","messagePattern":"user namespace configuration: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cri/server/podsandbox/helpers_linux.go","lineNumber":387,"sourceCode":"\t\t\treturn nil, nil, fmt.Errorf(\"can't use user namespace mode %q without UID and GID mappings\", mode)\n\t\t}\n\tdefault:\n\t\treturn nil, nil, fmt.Errorf(\"unsupported user namespace mode: %q\", mode)\n\t}\n\n\treturn uids, gids, nil\n}\n\nfunc snapshotterRemapOpts(nsOpts *runtime.NamespaceOption) ([]snapshots.Opt, error) {\n\tsnapshotOpt := []snapshots.Opt{}\n\tusernsOpts := nsOpts.GetUsernsOptions()\n\tif usernsOpts == nil {\n\t\treturn snapshotOpt, nil\n\t}\n\n\tuids, gids, err := parseUsernsIDs(usernsOpts)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"user namespace configuration: %w\", err)\n\t}\n\n\tif usernsOpts.GetMode() == runtime.NamespaceMode_POD {\n\t\tsnapshotOpt = append(snapshotOpt, containerd.WithRemapperLabels(0, uids[0].HostID, 0, gids[0].HostID, uids[0].Size))\n\t}\n\treturn snapshotOpt, nil\n}\n","sourceCodeStart":369,"sourceCodeEnd":395,"githubUrl":"https://github.com/containerd/containerd/blob/4246446a2bf7d03837b0244118d858799393bd80/internal/cri/server/podsandbox/helpers_linux.go#L369-L395","documentation":"This error wraps any failure from parseUsernsIDs while building snapshotter options for a pod sandbox with user namespace (userns) options. The library throws it because invalid or malformed user/group ID mappings in the pod's userns configuration make it impossible to construct correct snapshotter remap labels, and proceeding would produce a sandbox with wrong file ownership. It is a pre-flight validation failure of the user namespace configuration, not a runtime container failure.","triggerScenarios":"A pod sandbox is created with UserNamespace options set (usernsOpts != nil) and parseUsernsIDs fails - e.g. the pod spec's securityContext userNamespace mode is POD/TABULAR but uids/gids mappings are empty, have size 0, non-integer hostID/containerID values, or invalid bounds.","commonSituations":"Kubelet passes a pod spec with userNamespaces configured but malformed uidMappings/gidMappings; cluster upgraded to userns support but CRI plugin config or runtime lacks matching support; user manually crafts a CRI PodSandboxConfig with empty or zero-size ID ranges.","solutions":["Fix the pod spec's userNamespace uidMappings/gidMappings so each entry has valid, non-zero size and in-range hostID/containerID integers","Verify the CRI runtime (containerd + snapshotter) supports user namespace remapping and the configured snapshotter supports remap labels","Check kubelet feature gates/config for user namespaces are consistent with the runtime version","Inspect the wrapped error (%w) from parseUsernsIDs for the exact mapping entry that failed"],"exampleFix":"// before: pod spec with zero-size mapping\n// uidMappings: [{hostID: 0, containerID: 0, size: 0}]\n// after: valid mapping\n// uidMappings: [{hostID: 165536, containerID: 0, size: 65536}]","handlingStrategy":"validation","validationCode":"// validate userns mappings before submitting pod spec\nfunc validUserns(u *runtime.UserNamespaceOptions) bool {\n  if u == nil { return true }\n  uids, gids := u.GetUids(), u.GetGids()\n  if u.GetMode() == runtime.NamespaceMode_POD && (len(uids) == 0 || len(gids) == 0) { return false }\n  for _, m := range append(uids, gids...) {\n    if m.GetSize() <= 0 || m.GetHostID() < 0 || m.GetContainerID() < 0 { return false }\n  }\n  return true\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always specify non-zero-size uid/gid mappings when enabling pod-level user namespaces","Verify the runtime and snapshotter support userns remapping before enabling the feature","Test pod creation in a staging cluster after enabling userns feature gates"],"tags":["userns","cri","containerd","validation","configuration"],"backgroundTag":"invalid-userns-id-mapping","analyzedSha":"4246446a2bf7d03837b0244118d858799393bd80","analyzedAt":"2026-09-02T00:14:43.053Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}