Fix Multistage Builds Gone Wrong: 5 Pitfalls for Dev Teams

Multistage builds are a cornerstone of efficient Docker workflows, promising smaller images, faster CI/CD, and cleaner separation of concerns. Yet, many teams implement them incorrectly, inadvertently introducing complexity, bloat, and fragility. This guide identifies five common pitfalls and provides actionable fixes to help your team get the most out of multistage builds.

1. The High Cost of Broken Multistage Builds: Why It Matters

When multistage builds go wrong, the consequences ripple across your entire development lifecycle. Image sizes balloon, CI pipeline times increase, and developers lose confidence in the build process. One team I worked with saw their final image size jump from 150 MB to over 1.2 GB after a poorly structured multistage build—negating the very purpose of using this pattern. The root cause? They had inadvertently included build tools and intermediate artifacts in the final stage by misusing COPY instructions.

Understanding the Stakes: A Composite Scenario

Consider a typical microservices project with five services. Each service uses a multistage build. If even one service has a flawed stage separation, the entire deployment pipeline suffers. In one anonymized case, a team spent three weeks debugging random CI failures that traced back to a single stage that pulled the wrong base image. The fix was simple—reordering COPY commands and using explicit stage names—but the lost productivity was substantial. This illustrates how seemingly minor mistakes compound in complex systems.

Why Teams Fall into These Traps

Many teams adopt multistage builds without fully understanding the underlying mechanics. They copy examples from documentation without considering their specific dependency trees or cache invalidation patterns. A common oversight is treating all stages as independent, when in fact they share a build context and layer cache. Without explicit stage naming and targeted COPY instructions, the Docker daemon cannot optimize caching, leading to repeated rebuilds of unchanged layers.

Another factor is the pressure to deliver quickly. Teams prioritize getting a working image over an optimized one, accepting temporary workarounds that become permanent technical debt. Over time, the build file accumulates unnecessary layers, redundant commands, and deprecated dependencies. Addressing these issues requires a mindset shift from “make it work” to “make it efficient.”

The key takeaway is that multistage builds are not a silver bullet. They require deliberate design, ongoing maintenance, and a clear understanding of how Docker layers interact. In the following sections, we will dissect the five most common pitfalls and provide concrete solutions you can apply today.

2. Pitfall 1: Cache Mismanagement and Layer Bloat

One of the most frequent mistakes in multistage builds is ignoring how Docker caches layers across stages. When developers place frequently changing instructions early in a stage, they invalidate the cache for all subsequent layers, forcing a full rebuild. This is especially harmful in CI environments where builds are executed from scratch. A typical scenario: a team adds a COPY for application source code before installing system packages, causing the package installation to re-run on every code change.

How Cache Invalidation Works in Multistage Builds

Each instruction in a Dockerfile creates a layer. Docker caches these layers based on the instruction text and the files involved. If a layer changes, all downstream layers must be rebuilt. In a multistage build, stages are independent, but layers within each stage follow the same caching rules. The challenge is that intermediate stages often share base images, but their layers are not shared across stages unless explicitly tagged. For example, if stage 1 installs build dependencies and stage 2 copies artifacts from stage 1, the cache for stage 1 is only reused if the stage 1 Dockerfile instructions are identical to a previous build.

Practical Steps to Fix Cache Mismanagement

To minimize cache invalidation, order your Dockerfile instructions from least to most frequently changing. Start with base image declarations, then install system packages, then add configuration files, and finally copy application source code. Use the --mount=type=cache feature available in BuildKit to persist package manager caches across builds. For example, for apt-get, you can cache the /var/cache/apt directory. Another technique is to use specific stage names when copying artifacts: COPY --from=builder /app/out /app/. This avoids copying entire stages and reduces layer count. Also, consider combining multiple RUN commands into one to reduce layer count, but be mindful that this can make debugging harder.

Additionally, leverage Docker’s --cache-from flag in CI to pull a previously built image as a cache source. This is particularly effective when combined with a registry that stores intermediate images. One team I observed reduced their build times by 60% simply by implementing cache-from with a dedicated cache registry. They also added a nightly job that rebuilt the cache base to prevent it from becoming stale. The result was consistent build times under 5 minutes, down from 15.

Finally, audit your Dockerfile regularly with tools like dive to inspect layer sizes and identify redundant files. A common finding is that developers accidentally leave temporary files from build steps in the final image. By removing these in the same RUN command that creates them, you prevent them from being persisted in layers.

3. Pitfall 2: Over-Coupling Build Stages

Another common error is creating stages that are too tightly coupled, meaning that changes in one stage force rebuilds in subsequent stages even when the final output is unchanged. This often happens when developers use generic COPY instructions that copy entire build contexts instead of specific artifacts. For example, copying the entire /app directory from a builder stage may include source files that are not needed in the runtime stage, causing unnecessary cache invalidation.

Identifying Coupling in Your Dockerfile

Look for patterns like COPY --from=build /app /app without specifying which subdirectories are needed. The runtime stage may only require the compiled binary or static assets, but copying everything brings along intermediate files like .o objects or node_modules that are not used. Beyond bloating the image, this coupling means that any change to any file in the source directory invalidates the cache for the entire COPY instruction, even if the final binary is identical. In one composite scenario, a team had a JavaScript frontend and a Go backend in the same repository. Their Dockerfile copied the entire repo into both stages, causing frontend changes to trigger a full backend rebuild. The fix was to separate the builds into distinct stages and copy only the relevant output directories.

Strategies for Decoupling Stages

First, be explicit about what you copy. Use multiple COPY instructions to transfer only the necessary files. For example, COPY --from=builder /app/build /usr/share/nginx/html for a static site. Second, use stage aliases and targets to isolate dependencies. If your build process requires multiple tools (e.g., Node.js for frontend, Go for backend), create separate intermediate stages for each and then a final stage that combines outputs. Third, consider using multi-project repositories where each service has its own Dockerfile, reducing cross-contamination. However, this adds complexity in orchestration, so weigh the trade-offs.

Another effective pattern is to use build arguments to conditionally include or exclude stages. For instance, you can create a debug stage that includes development tools, but for production builds, you skip that stage using --target=production. This keeps the production image lean while allowing developers to test with full tooling locally. One team I worked with used this approach to reduce their production image from 800 MB to 200 MB. They also added a CI check that failed if the image size exceeded a threshold, enforcing discipline.

Finally, document the purpose of each stage in comments within the Dockerfile. This helps new team members understand the coupling points and avoid introducing accidental dependencies. Over time, as the project evolves, revisit the stage structure to ensure it still aligns with the actual build requirements.

4. Pitfall 3: Ignoring Build-Time vs. Runtime Dependencies

A fundamental principle of multistage builds is separating build-time dependencies (compilers, SDKs, header files) from runtime dependencies (libraries, binary assets). Yet, many teams fail to enforce this separation, resulting in images that contain unnecessary tools that increase size and attack surface. For example, including gcc or python-dev in a final image meant to run a compiled Go binary is both wasteful and a security risk.

The Security and Performance Implications

Every unnecessary package in your image is a potential vulnerability. According to industry reports, over 30% of container vulnerabilities originate from packages that are not needed at runtime. In a multistage build, it is tempting to reuse the same base image for both build and runtime stages, especially when the base image is small (e.g., alpine). However, even alpine includes tools like apk and shell that could be exploited. The best practice is to use a distroless image or a minimal scratch image for the final stage, copying only the compiled binary and required libraries. For interpreted languages like Python, use a slim base image and copy only the necessary packages using pip with --no-cache-dir. In one case, a team reduced their Python image from 1.2 GB to 180 MB by switching to a distroless base and using multi-stage to install dependencies into a separate stage, then copying only the site-packages.

How to Properly Separate Dependencies

Start by analyzing your application’s runtime dependencies. For compiled languages, use ldd to list required shared libraries and copy them into the final stage. Tools like dockerize can help. For interpreted languages, use dependency files (requirements.txt, package.json) and install only production dependencies. In your Dockerfile, create a “build” stage that installs all tools, compiles the code, and produces artifacts. Then, in the final stage, copy only the artifacts and any runtime libraries. Use --from=build to copy files, but avoid copying entire directories. For example: COPY --from=build /app/myapp /usr/local/bin/. Alternatively, use a --chown flag to ensure correct permissions.

Also, consider using Docker’s --link flag for COPY instructions to share layers across stages more efficiently. This is a newer feature that can reduce duplication. Another technique is to use a common base image for both build and runtime stages that contains only the OS basics, then add build tools in the build stage and remove them before the final stage. However, this can be error-prone; it is cleaner to use distinct base images.

Lastly, integrate security scanning into your CI pipeline. Tools like Trivy or Clair can detect vulnerabilities in your final image. If they flag a package that should not be there, it is a sign that your dependency separation is incomplete. One team I know set a policy: if the image contains any package from the build stage, the pipeline fails. This forced them to refine their COPY instructions until the image was minimal.

5. Pitfall 4: Misusing Build Targets and Stage Names

Multistage builds allow you to define multiple targets with the --target flag, enabling different builds for development, testing, and production. However, many teams either do not use targets at all or use them inconsistently, leading to confusion and duplicated code. Without targets, developers often create separate Dockerfiles for each environment, which contradicts the purpose of multistage builds. Alternatively, they use the same final stage for all environments, bloating the development image with production artifacts.

The Value of Named Targets

Named targets allow you to build specific stages in isolation. For example, you can have a “dev” stage that includes hot-reload tools and debuggers, a “test” stage that runs unit tests, and a “prod” stage that produces a minimal image. By running docker build --target=dev ., developers get a full-featured environment, while CI uses --target=prod for deployment. This pattern reduces the need for conditional logic in entrypoint scripts and makes the build process transparent. One team I assisted had a single Dockerfile with five stages: base, dependencies, build, test, and production. The test stage ran unit tests and produced a coverage report, which was then copied out via a volume. This eliminated the need for a separate test Dockerfile and ensured test dependencies were not included in production.

Common Mistakes and How to Fix Them

A frequent mistake is not naming stages explicitly, relying on default names like “stage-0” or “stage-1”. This makes it hard to reference stages in COPY --from= instructions and leads to errors when stages are reordered. Always assign descriptive names like “builder”, “dependencies”, or “runtime”. Another mistake is using the same stage for multiple purposes, such as running tests and building artifacts in the same stage. This couples test dependencies with build dependencies, increasing image size. Fix by splitting into separate stages. Also, avoid using --target in production builds that include test stages, as that would pull in test dependencies. Always specify the correct target.

Additionally, be cautious with the --cache-from flag when using targets. If you cache a stage that is not the target, the cache may not be reused correctly. In CI, build the intermediate stages first and push them to a registry, then reference them with --cache-from. This ensures that subsequent builds can reuse layers even if the final target changes. One team reduced their CI build time by 40% by caching each named stage separately. They used a script that built and pushed each stage as a separate tag, then referenced those tags in the final build.

Finally, document the purpose of each target in comments. Use ARG to define variables that differ per target, but avoid overcomplicating. The goal is clarity and maintainability, not cleverness.

6. Pitfall 5: Neglecting Image Security and Size Audits

Even with a well-structured multistage build, teams often neglect to audit the final image for security vulnerabilities and unnecessary bloat. This is a critical oversight because multistage builds can inadvertently include sensitive data, such as API keys or source code, if COPY instructions are too broad. Moreover, without regular audits, images accumulate layers that contain obsolete libraries or debug symbols, increasing the attack surface.

Real-World Security Incidents

I recall a composite incident where a team discovered that their production container included a .env file with database credentials. The file had been copied from the builder stage because the developer used COPY . /app instead of copying only the compiled binary. The credentials were then accessible to anyone who could pull the image. This type of leak is unfortunately common. Another scenario: a team used a base image that had a known critical vulnerability, and because they never scanned, they deployed it to production for months. The fix was to integrate scanning into the build pipeline and enforce a policy that images with high-severity vulnerabilities are not deployed.

Best Practices for Auditing and Hardening

First, use a minimal base image for the final stage. Distroless images are recommended because they contain only your application and its runtime dependencies, without a shell or package manager. If you must use a full OS, choose a slim variant and remove unnecessary tools in the same RUN command that installs packages. Second, use multi-stage to ensure that build artifacts like .git folders, test reports, and temporary files are never copied to the final image. Third, scan your image with tools like Trivy, Grype, or Snyk. Integrate this into your CI pipeline so that every build is scanned before being pushed to a registry. Set a threshold: if the scan finds critical vulnerabilities, fail the build.

Additionally, consider using Docker’s built-in docker scout command to analyze images. It can compare your image against a database of known vulnerabilities and suggest fixes. Another technique is to use a .dockerignore file to exclude sensitive files from the build context. This prevents them from being included in any stage, even accidentally. Review the .dockerignore regularly to ensure it is up to date.

Finally, monitor your image sizes over time. If a new version of the image is significantly larger, investigate what changed. Use tools like dive to inspect layers and identify where space is being consumed. One team set up a dashboard that tracked image sizes across all their services, alerting them when a size increased by more than 10% compared to the previous build. This proactive approach helped them catch bloat early.

7. Mini-FAQ: Common Questions About Multistage Builds

This section addresses frequently asked questions that arise when teams adopt multistage builds. The answers are based on common patterns and community best practices as of May 2026.

Q1: Should I use one Dockerfile or multiple Dockerfiles?

One Dockerfile with multiple stages is usually sufficient. Multiple Dockerfiles become necessary only when builds require completely different base images or dependency chains, such as when one service uses Python and another uses Go. Even then, you can use a single Dockerfile with conditional stages via build args. However, if the build logic becomes too complex, separate Dockerfiles with a shared base can improve readability. The trade-off is maintenance overhead.

Q2: How do I handle private package registries in multistage builds?

Use Docker build secrets (e.g., --secret with BuildKit) to pass credentials without embedding them in the image. In the builder stage, mount the secret as a file and use it to authenticate. This avoids leaking credentials to the final image. Alternatively, use a dedicated CI user with limited permissions that is valid only for the build duration.

Q3: What is the best way to share layers across stages?

Use the --link flag in COPY instructions when available. This creates a hard link instead of copying, sharing the underlying data. This is most effective when copying from a previous stage within the same build. For cross-build sharing, use a cache registry with --cache-from.

Q4: Can I use multistage builds with Windows containers?

Yes, but be aware that Windows images are generally larger, and layer caching may behave differently due to file system differences. Use the same principles of ordering instructions and separating dependencies. However, consider using Linux containers if possible for smaller images.

Q5: How do I debug a multistage build?

Use the --target flag to build and run a specific stage. For example, docker build --target builder -t myapp:builder . then docker run -it myapp:builder sh. This allows you to inspect intermediate stages. Additionally, use docker history to view layer commands and sizes. Tools like dive provide a visual interface for layer inspection.

Q6: When should I avoid multistage builds?

For very simple applications that require only a single base image and no compilation, multistage builds add unnecessary complexity. Also, if your build process is already fast and images are small, the overhead may not be justified. Evaluate the trade-off between complexity and benefit. For most production applications, however, multistage builds are recommended.

8. Moving Forward: Building Better Multistage Workflows

Multistage builds are a powerful tool, but they require deliberate design and ongoing attention. The five pitfalls covered in this guide—cache mismanagement, over-coupling stages, ignoring dependency separation, misusing targets, and neglecting security audits—are common but avoidable. By applying the solutions discussed, your team can achieve leaner images, faster builds, and a more secure deployment pipeline.

Actionable Next Steps

First, audit your existing Dockerfiles. Identify which stages are poorly ordered or unnecessarily coupled. Run a tool like dive to inspect layer sizes. Second, implement a scanning step in your CI pipeline to catch vulnerabilities and size regressions automatically. Third, adopt named targets and document them. Fourth, train your team on the principles of layer caching and dependency separation. Consider holding a workshop where you review a problematic Dockerfile and refactor it together. Fifth, monitor build times and image sizes over time, and set thresholds that trigger alerts when they deviate.

Remember that optimization is an iterative process. Start with the most impactful changes—like separating build and runtime dependencies—and then refine. Use the community resources available, such as Docker’s official documentation and the BuildKit repository, to stay updated on new features like --link and cache mounts. Finally, share your learnings with the broader team to foster a culture of continuous improvement. With these practices, your multistage builds will become a reliable asset rather than a source of frustration.