{"record":{"id":"41946210a6211a62","repo":"GoogleContainerTools/skaffold","slug":"statuscheck-container-waiting-unknown","errorCode":"STATUSCHECK_CONTAINER_WAITING_UNKNOWN","errorMessage":"container %s in error: %v","messagePattern":"container (.+?) in error: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"pkg/diag/validator/validator.go","lineNumber":379,"sourceCode":"\t\t// container is waiting to run. This could be because one of the init containers is\n\t\t// still not completed\n\t\treturn proto.StatusCode_STATUSCHECK_POD_INITIALIZING, nil, nil\n\tcase containerCreating:\n\t\treturn proto.StatusCode_STATUSCHECK_CONTAINER_CREATING, nil, fmt.Errorf(\"creating container %s\", c.Name)\n\tcase crashLoopBackOff:\n\t\t// TODO, in case of container restarting, return the original failure reason due to which container failed.\n\t\tsc, l := getPodLogs(po, c.Name, proto.StatusCode_STATUSCHECK_CONTAINER_RESTARTING)\n\t\treturn sc, l, fmt.Errorf(\"container %s is backing off waiting to restart\", c.Name)\n\tcase ImagePullErr, ImagePullBackOff, ErrImagePullBackOff:\n\t\treturn proto.StatusCode_STATUSCHECK_IMAGE_PULL_ERR, nil, fmt.Errorf(\"container %s is waiting to start: %s can't be pulled\", c.Name, c.Image)\n\tcase runContainerError:\n\t\tmatch := runContainerRe.FindStringSubmatch(c.State.Waiting.Message)\n\t\tif len(match) != 0 {\n\t\t\treturn proto.StatusCode_STATUSCHECK_RUN_CONTAINER_ERR, nil, fmt.Errorf(\"container %s in error: %s\", c.Name, trimSpace(match[3]))\n\t\t}\n\t}\n\tlog.Entry(context.TODO()).Debugf(\"Unknown waiting reason for container %q: %v\", c.Name, c.State)\n\treturn proto.StatusCode_STATUSCHECK_CONTAINER_WAITING_UNKNOWN, nil, fmt.Errorf(\"container %s in error: %v\", c.Name, c.State.Waiting)\n}\n\nfunc newPodStatus(n string, ns string, p string) *podStatus {\n\treturn &podStatus{\n\t\tname:      n,\n\t\tnamespace: ns,\n\t\tphase:     p,\n\t\tae: proto.ActionableErr{\n\t\t\tErrCode: proto.StatusCode_STATUSCHECK_SUCCESS,\n\t\t},\n\t}\n}\n\nfunc trimSpace(msg string) string {\n\treturn strings.Trim(msg, \" \")\n}\n\nfunc getPodLogs(po *v1.Pod, c string, sc proto.StatusCode) (proto.StatusCode, []string) {","sourceCodeStart":361,"sourceCodeEnd":397,"githubUrl":"https://github.com/GoogleContainerTools/skaffold/blob/a1189de023efc32d4b8e11f395acc678aa555011/pkg/diag/validator/validator.go#L361-L397","documentation":"Fallback branch of extractErrorMessageFromWaitingContainerStatus: the container is Waiting but Skaffold does not recognize the waiting reason (it did not match CrashLoopBackOff, ImagePullBackOff, or the run-container regex). It returns STATUSCHECK_CONTAINER_WAITING_UNKNOWN and embeds the whole Waiting state struct for debugging.","triggerScenarios":"getContainerStatus finds a pod container in Waiting state whose Reason is none of the known constants (or Message does not match runContainerRe), e.g. a newly introduced kubelet reason or ContainerCreating timeouts.","commonSituations":"Container stuck in ContainerCreating because a PVC or ConfigMap is not bound; cluster upgraded to a Kubernetes version emitting a new waiting reason; CNI plugin slow so the container never leaves Waiting.","solutions":["Inspect the embedded Waiting state in the error and the pod with kubectl describe pod / kubectl events to find the actual blocking reason.","Ensure dependent resources (PVC, ConfigMap, Secret, CNI) exist and are bound before running the skaffold health check.","If the reason is a legitimate new Kubernetes waiting reason, update the validator's known-reason switch in pkg/diag/validator/validator.go to map it."],"exampleFix":"// before\nc.name: container stuck Waiting, unknown reason\n// after\nkubectl -n <ns> describe pod <pod>  # then create the missing ConfigMap/PVC the pod references","handlingStrategy":"validation","validationCode":"// Ensure referenced resources exist before deploying\nkubectl -n <ns> get configmap,secret,pvc\nkubectl -n <ns> get events --field-selector type=Warning","typeGuard":null,"tryCatchPattern":"try {\n  await skaffold.run(...);\n} catch (e) {\n  if (String(e).includes('CONTAINER_WAITING_UNKNOWN')) {\n    // capture pod state for diagnosis and retry after infra is fixed\n    console.error('Pod stuck Waiting with unknown reason; run kubectl describe pod');\n  }\n  throw e;\n}","preventionTips":["Pre-create ConfigMaps/Secrets/PVCs referenced by pods","Keep cluster CNI and Kubernetes versions compatible with your workloads","Watch kubectl get events during deploys to catch Waiting states early"],"tags":["kubernetes","pod-scheduling","skaffold","health-check"],"backgroundTag":"container-waiting-unknown-reason","analyzedSha":"a1189de023efc32d4b8e11f395acc678aa555011","analyzedAt":"2026-09-05T12:09:27.064Z","contentChangedAt":"2026-09-05T12:09:27.064Z","schemaVersion":2},"datasetVersion":"2026-09-12T17:17:11.597Z"}