How to fix Exit Code 128 in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 218 views

Exit code 128 indicates a container startup failure—the runtime could not execute the specified command. Verify the command exists, check for mount issues, or fix invalid exit codes in scripts.

Quick fix

Fixes Exit Code 128

kubectl describe pod <pod-name>
  1. Check pod events and container state
  2. Verify the command exists in the image
  3. Check for volume mount issues
  4. Fix invalid exit codes in scripts
kubernetes — error
kubectl describe pod <pod-name>
Exit Code 128

What this error means

Exit code 128 in Kubernetes indicates that the container runtime failed to start the specified command. This code has two related meanings in Unix systems: First, 128 is the base number for fatal signal exit codes (signal N = exit code 128 + N). Second, exit code 128 alone means "invalid argument to exit" in bash—when a process attempts to exit with a value outside the valid 0-255 range. In Kubernetes, exit code 128 typically appears as ContainerCannotRun, meaning the container failed before the application even started. The command specified in the pod or image doesn't exist, can't be found, or the execution environment isn't properly configured.

Typical symptoms

  • Container fails immediately after creation with exit code 128
  • Pod enters CrashLoopBackOff without running application code
  • Events show ContainerCannotRun or StartError status
  • Error messages include executable file not found in PATH
  • Mounting errors like no such device or error mounting to rootfs
  • Git or npm commands fail with exit code 128 when accessing private repos
  • ConfigMap changes during pod startup cause mount failures

Common causes

  1. Command specified in Dockerfile or pod spec does not exist in image
  2. Entrypoint or CMD path is incorrect or misspelled
  3. Shell script passes invalid exit code (outside 0-255 range)
  4. Volume mount race condition during ConfigMap or Secret updates
  5. Missing executable permissions on the command
  6. Container image corrupted or incomplete
  7. Security context prevents command execution
  8. SSH authentication failures in git-based package installations

How to fix "Exit Code 128"

1Check pod events and container state

Get detailed error information:

bash
kubectl describe pod <pod-name>

Look for the Last State section and Events. Common messages include:
- "ContainerCannotRun" - command startup failure
- "StartError: failed to create containerd task" - runtime issue
- "executable file not found in $PATH" - missing binary

2Verify the command exists in the image

Test the image locally:

bash
# Check if command exists
docker run --rm <image>:<tag> which <command>

# List what's in the expected path
docker run --rm <image>:<tag> ls -la /app/

# Try running the exact command
docker run --rm <image>:<tag> <your-command>

If the command doesn't exist, fix your Dockerfile to include it.

3Check for volume mount issues

Exit code 128 can occur when volumes fail to mount:

bash
kubectl describe pod <pod-name> | grep -A 10 "Volumes:"
kubectl get pvc  # Check PersistentVolumeClaim status

Common issues:
- ConfigMap modified while pod is starting
- PVC not bound to a PV
- NFS or cloud storage mount failures

Avoid editing ConfigMaps during pod startup. Use immutable ConfigMaps for critical configs.

4Fix invalid exit codes in scripts

If your entrypoint script uses invalid exit values:

bash
# Wrong - exit code must be 0-255
exit 256  # Results in exit code 0
exit -1   # Results in exit code 255

# Correct
exit 1    # Valid error code
exit 0    # Success

Review your scripts for any dynamic exit codes that might exceed 255.

5Check security context and permissions

The container user may lack permission to execute:

yaml
securityContext:
  runAsUser: 1000
  runAsNonRoot: true

Ensure:
1. The binary has execute permissions for that user
2. SecurityContext doesn't block execution
3. No SELinux/AppArmor policies preventing startup

Test locally with the same user:

bash
docker run --user 1000 <image> <command>
6Debug with a shell override

If the container won't start, override to debug:

yaml
command: ["/bin/sh", "-c", "sleep infinity"]

Then exec in and investigate:

bash
kubectl exec -it <pod-name> -- /bin/sh

# Check if command exists
which mycommand
ls -la /app/entrypoint.sh

# Try running manually
/app/entrypoint.sh

Advanced notes

Exit code 128 from git operations (like npm install with git dependencies) usually indicates SSH key issues. Ensure your container has access to credentials for private repositories.

For ConfigMap race conditions, consider using init containers to wait for configuration to be ready, or use immutable ConfigMaps that don't change after creation.

In multi-stage Docker builds, exit code 128 often indicates the COPY --from stage reference is wrong or the binary wasn't built in the earlier stage. Verify each build stage produces the expected artifacts.

On managed Kubernetes (EKS, GKE, AKS), exit code 128 can also indicate node-level issues like disk pressure or container runtime problems. Check node conditions if multiple pods fail with this code.

Frequently asked questions

What does "Exit Code 128" mean?
Exit code 128 in Kubernetes indicates that the container runtime failed to start the specified command. This code has two related meanings in Unix systems: First, 128 is the base number for fatal signal exit codes (signal N = exit code 128 + N). Second, exit code 128 alone means "invalid argument to exit" in bash—when a process attempts to exit with a value outside the valid 0-255 range.
How do I fix "Exit Code 128"?
Exit code 128 indicates a container startup failure—the runtime could not execute the specified command. Verify the command exists, check for mount issues, or fix invalid exit codes in scripts.
What causes "Exit Code 128"?
Command specified in Dockerfile or pod spec does not exist in image Entrypoint or CMD path is incorrect or misspelled Shell script passes invalid exit code (outside 0-255 range)
Is the "Exit Code 128" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading