Docker Build Failure Recovery Prompt

This prompt is designed for containerization engineers and CI/CD pipeline operators who need to automatically recover from failed Docker image builds. The core job is to consume a Dockerfile and the complete build error log, then produce a corrected Dockerfile that resolves the build failure while preserving the original intent. The prompt also generates layer optimization notes, helping teams improve build caching and image size in the same recovery step. This is not a general Dockerfile authoring assistant—it is a targeted recovery tool for build-time failures such as missing base images, COPY failures, RUN command errors, package installation conflicts, and multi-stage build misconfigurations.

Use this prompt when you have a concrete build failure with a captured error log and the offending Dockerfile. The prompt works best with deterministic, reproducible build errors rather than transient network or resource issues. It requires the full build context: the Dockerfile content, the exact error output from the build command, and optionally the build context structure if the error involves file paths. Do not use this prompt for runtime container debugging, orchestration-level failures (e.g., Kubernetes pod crashes), or security vulnerability scanning—those require different diagnostic workflows. The prompt assumes a single Dockerfile as input; multi-service builds with docker-compose or complex build arguments should be broken into individual Dockerfile recovery steps.

Before wiring this into an automated pipeline, ensure you have a validation harness that rebuilds the corrected Dockerfile in an isolated environment and runs a basic smoke test (e.g., container starts, expected process runs, health check passes). The prompt produces a corrected Dockerfile, but the fix may introduce subtle behavioral changes—layer reordering, base image version bumps, or package version shifts—that require human review for production images. For high-risk production deployments, route the corrected Dockerfile to a pull request workflow with mandatory human approval rather than auto-merging. The next section provides the copy-ready prompt template you can adapt to your specific build environment and error format.

The prompt below is designed to be dropped into an automated CI/CD recovery harness. It expects a failed Dockerfile and the corresponding build error log, and it instructs the model to act as a senior containerization engineer. The output is a corrected Dockerfile with a structured explanation of the fix and any layer-caching improvements. Use this template as the core instruction in a retry step after a docker build command returns a non-zero exit code.

textCopy
You are a senior containerization engineer debugging a failed Docker build.

Your task is to analyze the provided Dockerfile and the build error log, then produce a corrected Dockerfile that builds successfully.

## INPUT

[DOCKERFILE]

[BUILD_ERROR_LOG]

## CONSTRAINTS

- Preserve the original application logic and entrypoint behavior.
- Do not change base image versions unless the error log indicates an incompatibility.
- Prefer minimal fixes over rewrites.
- If the error is a transient network or registry issue, note that in your explanation and suggest a retry rather than a Dockerfile change.
- If the error is caused by a missing file or incorrect COPY path, verify the path against common project structures and suggest the likely correct path.
- If the error is a layer-caching issue, reorder instructions to maximize cache reuse (e.g., move rarely-changing COPY commands before frequently-changing ones).

## OUTPUT_SCHEMA

Return a JSON object with the following fields:

{
  "diagnosis": "One-sentence summary of the root cause.",
  "fix_type": "One of: dependency_version, file_path, syntax_error, layer_order, network_retry, permission, resource_limit, multi_stage_fix, unknown",
  "corrected_dockerfile": "The full corrected Dockerfile as a single string with newlines escaped as \n.",
  "changes": [
    {
      "line_range": "Lines 12-14",
      "before": "RUN apt-get install curl",
      "after": "RUN apt-get update && apt-get install -y curl",
      "reason": "Missing apt-get update before install causes 404 errors on stale package lists."
    }
  ],
  "layer_optimization_notes": "Optional string describing any reordering for cache efficiency.",
  "confidence": "high | medium | low"
}

## EXAMPLES

### Example 1: Missing apt-get update

Input Dockerfile:
FROM ubuntu:22.04
RUN apt-get install -y curl

Error Log:
E: Unable to locate package curl

The command '/bin/sh -c apt-get install -y curl' returned a non-zero code: 100

Output:
{
  "diagnosis": "Package list is stale; apt-get update is required before installing packages.",
  "fix_type": "syntax_error",
  "corrected_dockerfile": "FROM ubuntu:22.04\nRUN apt-get update && apt-get install -y curl",
  "changes": [
    {
      "line_range": "Line 2",
      "before": "RUN apt-get install -y curl",
      "after": "RUN apt-get update && apt-get install -y curl",
      "reason": "apt-get update refreshes the package index, preventing 404 errors."
    }
  ],
  "layer_optimization_notes": null,
  "confidence": "high"
}

### Example 2: COPY path not found

Input Dockerfile:
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY src/ ./src/

Error Log:
COPY failed: file not found in build context or excluded by .dockerignore: stat package*.json: no such file or directory

Output:
{
  "diagnosis": "package.json is not in the build context root; it may be in a subdirectory or the build context is misconfigured.",
  "fix_type": "file_path",
  "corrected_dockerfile": "FROM node:18-alpine\nWORKDIR /app\nCOPY ./app/package*.json ./\nRUN npm ci --only=production\nCOPY ./app/src/ ./src/",
  "changes": [
    {
      "line_range": "Line 3",
      "before": "COPY package*.json ./",
      "after": "COPY ./app/package*.json ./",
      "reason": "The build context likely points to the repository root, and the application is in an 'app' subdirectory."
    },
    {
      "line_range": "Line 5",
      "before": "COPY src/ ./src/",
      "after": "COPY ./app/src/ ./src/",
      "reason": "Consistent path correction for the source directory."
    }
  ],
  "layer_optimization_notes": "Layer order is already optimal: package files are copied before source to maximize npm ci cache reuse.",
  "confidence": "medium"
}

## RISK_LEVEL

[RISK_LEVEL]

If RISK_LEVEL is "high", include a warning in the diagnosis and set confidence to "low" if the fix involves changing base images, altering entrypoints, or modifying multi-stage build logic without full context.

To adapt this template for your pipeline, replace the [DOCKERFILE] and [BUILD_ERROR_LOG] placeholders with the actual file content and error output from your build system. Set [RISK_LEVEL] to "high" for production deployments, "medium" for staging, or "low" for development environments. The JSON output schema is designed to be machine-readable: your harness should parse the corrected_dockerfile field, write it to disk, and re-run docker build. If confidence is "low" or fix_type is "unknown", route the suggestion to a human for review before applying. Always validate the corrected Dockerfile with docker build --dry-run or a linting tool like Hadolint before committing the change to your repository.

This prompt is designed to be called programmatically after a docker build command exits with a non-zero code. The application harness should capture the full build log from stdout/stderr, read the original Dockerfile, and assemble the prompt with both artifacts. Do not truncate the error log; the model needs the complete context to diagnose multi-stage build failures, missing file errors, and layer-specific issues. The harness should also inject the target platform and any build arguments used so the model can reason about architecture mismatches.

The implementation should follow a strict retry budget. After receiving the corrected Dockerfile from the model, the harness must write it to a temporary location and execute docker build again. If the build succeeds, proceed to a smoke test that runs the image with a basic health check command (e.g., docker run --rm [image] [healthcheck]). If the build fails again, feed the new error log back into the prompt for a second attempt, but cap total retries at three. After three failures, log the full interaction, flag the build for human review, and do not deploy. Each retry cycle should be logged with the prompt version, model used, build duration, and whether the fix was applied successfully.

For model selection, use a capable code-generation model such as claude-sonnet-4-20250514 or gpt-4o. Avoid smaller or faster models for this task because Dockerfile repair requires precise syntax knowledge, understanding of layer caching implications, and the ability to reason about build context. If the pipeline runs in a cost-sensitive environment, you can attempt the first retry with a smaller model and escalate to a larger model on the second attempt. Always validate the model's output before applying it: check that the response contains a valid Dockerfile in a fenced code block, that it does not introduce unvalidated COPY or ADD instructions from unexpected paths, and that it preserves the original image base and essential build stages. Never apply a model-generated Dockerfile directly to production without a successful build and smoke test in the pipeline.