Docker images can balloon to several gigabytes when a single instruction goes wrong. A misplaced `COPY` line, a forgotten `.dockerignore` file, or an unpinned base image is often all it takes to turn a lean build into a slow, bloated, and risky one. The frustrating part? Most of these problems are entirely avoidable once you know where they hide.
Docker itself has become the default packaging format for modern software. According to Wikipedia’s overview of Docker), the platform launched in 2013 and now underpins container workflows across nearly every major cloud provider. That popularity means millions of developers write Dockerfiles, and many repeat the same handful of errors. This guide walks through the most common Docker mistakes, why they hurt, and what actually works in practice. (Docker (software)))
Treating the `latest` Tag as a Safe Default
Pulling `node:latest` or `python:latest` feels convenient. It is also one of the most common sources of “it worked yesterday” bugs. The `latest` tag is simply a default label applied when no tag is specified. It is not a guarantee of the newest or most stable release, and the underlying image can change without warning.
The fix is straightforward: pin a specific version, ideally with a digest for critical production images. Instead of `FROM postgres:latest`, write `FROM postgres:16.2`. This makes builds reproducible. When something breaks, you know exactly which base image you were running.
A practical habit that works well: pin the minor version in development and the full version plus digest in production. You get flexibility where you need it and stability where it counts.
Skipping the `.dockerignore` File
Every `docker build` sends a build context to the Docker daemon. Without a `.dockerignore` file, that context can include `node_modules`, `.git`, log files, local environment files, and test artifacts. The results are predictable: slower builds, larger images, and occasionally leaked secrets.
A solid `.dockerignore` usually includes:
- `node_modules` and `vendor` directories
- `.git` and `.github`
- `*.log` and temporary files
- `.env` and other local config files
- Test coverage and build output folders
This single file often cuts build context size by 80 percent or more. It also prevents accidental copying of files you never intended to ship. If you have ever wondered why a build takes 90 seconds when it should take 10, the missing `.dockerignore` is a prime suspect. (How to take a screenshot on a mac)
Getting the Layer Order Wrong
Docker caches each Dockerfile instruction as a layer. Once the inputs to a layer change, that layer and every layer after it get rebuilt. This is where ordering matters enormously.
The classic mistake looks like this: copy the entire source code first, then run `npm install`. Every time a developer touches a single line of code, the dependency install re-runs from scratch. The correct order flips this:
- Copy only the dependency manifest (`package.json`, `requirements.txt`, `go.mod`).
- Install dependencies.
- Copy the rest of the source code.
- Build or run the application.
With this structure, dependencies stay cached until the manifest actually changes. Builds that once took minutes drop to seconds. It is one of the highest-leverage changes a team can make, and it costs nothing but a little reordering.
Ignoring Multi-Stage Builds
Shipping a compiler, build tools, and dev dependencies into production is a silent image-size killer. Multi-stage builds solve this by letting you compile in one stage and copy only the finished artifacts into a minimal final stage.
A typical pattern uses a full SDK image to build, then a slim runtime image to serve. The final image might shrink from 1.2 GB to under 200 MB. Smaller images mean faster pulls, quicker cold starts, and a smaller attack surface from fewer installed packages.
The mistake isn’t just forgetting multi-stage builds exist. It’s also stopping halfway: keeping build tools in the final stage “just in case.” If a binary or package isn’t needed at runtime, it doesn’t belong in the final image.
Running Containers as Root
By default, many base images run as root. That is a serious security risk. If an attacker compromises the application, they inherit root privileges inside the container, which makes container escapes and lateral movement far easier.
The remedy is to create a dedicated user and switch to it with the `USER` instruction:
- Add a non-root user during the build.
- Set proper file ownership on application directories.
- Switch to that user before the final `CMD` or `ENTRYPOINT`.
This is a small change with an outsized impact. Many security scanners flag root containers automatically, and some Kubernetes clusters now reject them by policy. Building the habit early saves painful rework later.
Baking Secrets Into Images
Hardcoding API keys, database passwords, or tokens into a Dockerfile is a mistake that keeps showing up in code reviews. Even if you delete the secret in a later layer, it remains embedded in the image history. Anyone with access to the image can extract it.
Environment variables set with `ENV` and build arguments passed with `ARG` are both visible in image metadata. They are not secret storage. For real secrets, use runtime injection through your orchestrator’s secret management, or use build-time secret mounts that never persist in the final layer.
The practical rule: if a value would be dangerous in a public GitHub repository, it should never appear in a Dockerfile.
Storing Data Inside the Container
Containers are ephemeral by design. Anything written to a container’s writable layer disappears when the container is removed. Yet teams still store uploaded files, database data, or logs inside the container filesystem, then act surprised when a redeploy wipes everything.
The correct approach is to use volumes or bind mounts for anything that must persist. Databases, user uploads, and log files all belong on mounted storage. The container should be treated as disposable: kill it, replace it, and lose nothing that matters.
A related mistake is confusing volumes with bind mounts. Volumes are managed by Docker and work well across environments. Bind mounts tie a container to a specific host path, which is fine for local development but fragile in production.
Overusing `docker system prune`
Cleanup commands feel harmless until they aren’t. Running `docker system prune –volumes` on a shared machine can delete stopped containers, unused networks, dangling images, and unused volumes that someone was counting on. The `–volumes` flag is especially dangerous because it removes data, not only images.
The safer habit is to inspect before pruning. Run `docker system df` to see what is actually consuming space, then target specific resources with `docker image prune` or `docker container prune`. On shared hosts, coordinate with teammates before running anything aggressive. (Docker Get Started)
Forgetting Healthchecks
A container that is “running” is not necessarily healthy. Without a `HEALTHCHECK` instruction, Docker treats any live process as healthy, even if the application is stuck, deadlocked, or returning errors.
Adding a healthcheck gives the orchestrator real signal. A simple HTTP check against a `/health` endpoint, or a command that verifies the process can respond, lets Docker and Kubernetes restart unhealthy containers automatically. It also improves load balancer behavior, since traffic stops routing to failing instances.
The mistake here is subtle: teams add healthchecks to databases and web servers but forget background workers, queue consumers, and scheduled jobs. Every long-running service benefits from a way to report its own health.
Copying Everything With `COPY..`
`COPY..` is convenient and dangerous. It copies the entire build context into the image, including files you never meant to ship. Combined with a missing `.dockerignore`, it can pull in local configs, editor files, and even credentials. (How to take a screenshot on windows)
The better pattern is explicit copying. List exactly what the application needs: source directories, configuration templates, and static assets. Explicit copies are self-documenting and catch mistakes early. When a new file is needed, the build fails loudly instead of silently including everything.
This also connects to a broader principle: treat the Dockerfile as a contract. Every line should state intent clearly.
Mismatching Local and Production Environments
A Dockerfile that works locally but fails in CI usually has an environment assumption baked in. Common culprits include hardcoded hostnames, missing environment variables, and architecture-specific binaries.
Building on Apple Silicon and deploying to x86 servers is a frequent trap. Images built for `linux/arm64` won’t run on `linux/amd64` hosts without emulation. The fix is to specify the target platform explicitly during build, and to test the production image locally before shipping.
Another practical tip: run the exact image in a staging environment before production. If the staging deploy uses the same image tag and configuration, surprises shrink dramatically.
Neglecting Image Scanning and Updates
Base images accumulate vulnerabilities over time. An image built six months ago may contain packages with known CVEs. Teams that build once and never rebuild inherit that risk silently.
The healthier workflow is to rebuild regularly, scan images in CI, and pin versions while still updating them deliberately. Automated dependency updates and scheduled rebuilds keep images current without manual toil. Scanning tools catch problems early, before they reach production.
This is less about perfection and more about rhythm. A monthly rebuild cycle beats a heroic cleanup every two years.
A Quick Comparison of Common Mistakes
| Mistake | Typical Symptom | Practical Fix |
|---|---|---|
| Using `latest` tag | Unpredictable builds | Pin specific versions |
| No `.dockerignore` | Slow builds, bloated images | Exclude unneeded files |
| Wrong layer order | Dependencies reinstall constantly | Copy manifests first |
| No multi-stage build | Gigabyte-sized images | Separate build and runtime stages |
| Running as root | Security scanner failures | Add and switch to non-root user |
| Secrets in Dockerfile | Leaked credentials | Use runtime secret injection |
Conclusion
Most Docker problems are not exotic. They come from defaults that feel convenient: the `latest` tag, `COPY..`, running as root, and skipping cleanup files. Each one is easy to fix once it is named, and together they account for the majority of slow builds and security findings teams encounter.
The path forward is a set of small, repeatable habits. Pin your versions. Write a real `.dockerignore`. Order your layers so dependencies cache properly. Use multi-stage builds. Run as a non-root user. Keep secrets out of images. Store data in volumes. These practices take an afternoon to adopt and pay off on every single deploy after that.
Docker rewards discipline more than cleverness. A Dockerfile that is boring, explicit, and reproducible will outperform a clever one every time. Start with the mistakes above, fix them one at a time, and the improvements compound quickly.
Making These Habits Stick
Knowing the mistakes is the easy part; changing team behavior is harder. The most effective approach is to encode these practices into automation rather than relying on code review vigilance. A few lightweight guardrails go a long way:
- Lint Dockerfiles in CI. Tools like Hadolint catch many of the issues above automatically—unpinned base images, missing `USER` instructions, and `latest` tags fail the build before review.
- Scan images on every push. Wire a scanner into the pipeline so vulnerabilities surface at build time, not after deployment.
- Add a template Dockerfile to your repo. New services start from a known-good structure with multi-stage builds, non-root users, and correct layer ordering already in place.
- Review the build context. A quick check of `docker build` output shows the context size; if it looks large, the `.dockerignore` needs attention.
None of these require new tooling budgets or platform migrations. They are configuration changes that turn good intentions into defaults. When the pipeline enforces a rule, nobody has to remember it during a rushed Friday deploy.
It also helps to treat Dockerfiles as living documents. Revisit them when base images release security patches, when build times creep upward, or when a new team member asks why a line exists. If no one can explain an instruction, it is probably safe to remove. The goal is not a perfect Dockerfile on day one, but one that gets a little leaner and safer with each pass.
