Exit Code 125
The Docker CLI command itself failed to run, often due to syntactically invalid parameters or driver failures before the container process could start.
Usually happens because:
- ☑ Invalid command line parameter flags
- ☑ Conflicting container name already exists
- ☑ Kernel security policies AppArmor blocks
🔍 Quick Checklist:
What is Exit Code 125?
Exit code 125 is an error status returned by the Docker CLI client indicating that the docker run command itself failed to initialize the container environment. Unlike exit codes 126 or 127 (which originate from inside the container during execution), exit code 125 originates from Docker itself before the container process has been started. Common triggers include specifying invalid flag parameters, attempting to bind non-existent local network ports, or encountering system runtime configuration conflicts.
Common Causes
- Invalid command line flags: Providing syntax errors (like -p instead of --publish, or mismatched quotation marks).
- System capabilities restriction: The host kernel restricts required container permissions (e.g. running under strict SELinux/AppArmor blocks).
- Conflicting container names: Attempting to run a new container using a name that is already allocated to another container on the system.
| Cause | Frequency |
|---|---|
| Invalid CLI flags or options syntax | ⭐⭐⭐⭐⭐ |
| Conflicting container name namespace | ⭐⭐⭐⭐ |
| Host security profiles (AppArmor/SELinux) block | ⭐⭐ |
Common Mistakes
- Mistaking exit code 125 for an application failure (it indicates the container itself was blocked from launching, meaning the code inside never ran).
- Declaring arguments in the wrong position relative to the image name (all docker flags must precede the image name; anything after the image name is treated as command arguments inside the container).
How to Fix
Docker Operations & Verification
How to verify and capture the exit code returned by the last run docker command in Linux and macOS shells.
docker run --invalid-flag-name alpine
echo $?
# Outputs: 125Platform Specific Fixes
Checking security profile policies (like AppArmor) on Linux servers.
# Check if AppArmor service is active
sudo systemctl status apparmor
# Run container bypassing default profiles
docker run --security-opt apparmor=unconfined -d nginxBest Practices
- Always check for running or stopped containers using `docker ps -a` before scripting name-specific runs.
- Use `--rm` flag to automatically clean up containers upon termination, freeing up the name namespace.
Frequently Asked Questions (FAQ)
Q: What is exit code 125?
Exit code 125 indicates that the Docker daemon or CLI client failed to start the container, meaning the problem lies in the command arguments or configuration, not the application inside the container.
Q: How does exit code 125 differ from 127?
Exit code 125 is thrown by Docker itself when the container fails to launch. Exit code 127 is thrown from inside the container when a specified command or binary is not found inside the image.
Q: Why does duplicate container names throw 125?
Because Docker cannot instantiate two containers with the same name. It will reject the creation phase and return exit code 125.
Q: How do I capture exit codes?
Immediately after running a docker command, run 'echo $?' on Linux/macOS or '$LastExitCode' inside PowerShell to capture the status.