Docker Compose Service Startup Failure Recovery Prompt

This prompt is designed for the moment after a docker compose up command fails with a non-zero exit code. It is a targeted recovery tool for platform engineers and developers who have already written a docker-compose.yml file and are staring at container logs or error output they cannot immediately resolve. The job-to-be-done is not initial file generation or architectural design; it is rapid, context-aware debugging of a runtime failure. The ideal user has the failing Compose file, the full terminal error output, and a need for a corrected service definition, environment block, or dependency map that can be applied directly to unblock their workflow.

Use this prompt when the failure is not a simple YAML syntax error—docker compose config can handle basic linting—but a logical or environmental mismatch. This includes port conflicts between services or with the host, invalid volume mount paths or permissions, environment variables that are missing, misspelled, or of the wrong type, and inter-service dependency chains where a critical backend is not yet healthy when a dependent service starts. The prompt instructs the model to act as a senior DevOps engineer, reasoning across the entire Compose file and error context to isolate the root cause. It is particularly effective when the error message is verbose or multi-layered, such as a Java stack trace from a container that crashed because a database URL was misconfigured.

Do not use this prompt for greenfield Compose file generation, architectural reviews, or multi-service orchestration design. It is not a substitute for a docker compose config syntax check, and it will not be effective if you provide only a generic error like 'container exited with code 1' without the associated logs. For failures involving external infrastructure—such as a cloud provider's managed database being unreachable due to a network ACL—this prompt can identify the symptom but will not have the context to fix the external resource. In those cases, pair the output with a cloud-specific recovery prompt. After receiving the corrected YAML snippet, always validate it with docker compose config and a dry-run docker compose up --no-start before applying it to a shared environment.

This prompt is designed to be pasted directly into your AI harness, LLM playground, or automated recovery pipeline. It accepts a failing Docker Compose file, the associated container logs, and any relevant environment context, then instructs the model to diagnose the root cause and produce a corrected service definition. The output is structured to be machine-readable, allowing your harness to parse the suggested fix and optionally apply it in a controlled retry loop.

textCopy
You are an expert DevOps engineer specializing in Docker and container orchestration. Your task is to diagnose a Docker Compose service startup failure and provide a corrected configuration.

## INPUT
- Failing Docker Compose file:
```yaml
[DOCKER_COMPOSE_YAML]

• Container logs or error output:

textCopy
[CONTAINER_LOGS]

• Additional context (optional): [ADDITIONAL_CONTEXT]

CONSTRAINTS

• Preserve the original service names and overall architecture unless they are the direct cause of the failure.
• Do not change the base image unless the specified tag is invalid or incompatible.
• If suggesting new environment variables, explain why they are needed.
• If modifying depends_on, ensure the dependency graph remains acyclic and logical.
• For port conflicts, suggest an alternative host port or identify the conflicting process.
• For volume mount errors, verify the host path exists and the container has correct permissions.

OUTPUT_SCHEMA

Respond with a valid JSON object containing the following fields: { "root_cause": "A concise, one-sentence summary of the primary failure cause.", "diagnosis": "A detailed explanation of the error, referencing specific lines from the logs and compose file.", "corrected_compose": "The full, corrected Docker Compose YAML content as a single string.", "changes_summary": ["A list of specific changes made, e.g., 'Changed port mapping from 80:80 to 8080:80'."], "requires_manual_intervention": true_or_false, "manual_steps": "If manual intervention is required, list the steps. Otherwise, set to null." }

RISK_LEVEL

This is a [RISK_LEVEL] operation. If [RISK_LEVEL] is 'high', flag any destructive changes (like volume re-creation) in requires_manual_intervention.

To adapt this template, replace the square-bracket placeholders with your actual data. [DOCKER_COMPOSE_YAML] should contain the raw text of your docker-compose.yml file. [CONTAINER_LOGS] should include the output from docker compose logs or the specific error message from the failing service. Use [ADDITIONAL_CONTEXT] to pass in details like the host OS, Docker version, or recent changes. Set [RISK_LEVEL] to 'low', 'medium', or 'high' to control the model's caution. The harness should parse the JSON output and, if requires_manual_intervention is false, can proceed to write the corrected_compose to a file and run docker compose up -d as a retry step. Always validate the corrected YAML with a linter before applying it to avoid introducing syntax errors.

This prompt is designed to be called programmatically after a docker compose up command exits with a non-zero code or when container health checks fail. The harness should capture the full compose file content, the complete stdout/stderr log output from the failed run, and any relevant environment variable files before constructing the prompt payload. Do not truncate logs prematurely—the model needs the full error context to diagnose issues like port conflicts, volume mount permission errors, or dependency service startup ordering problems. The harness must also inject the [OUTPUT_SCHEMA] placeholder with a strict JSON schema that defines the expected structure: a diagnosis string, a corrected_compose string containing the full corrected YAML, a changes array of objects describing each modification with field, before, after, and reason keys, and a requires_manual_review boolean flag for cases where the fix involves external resources like network creation or filesystem permissions.

Before executing the prompt, validate that the input compose file is syntactically valid YAML. If the file fails to parse, do not call the model—return a harness-level error indicating the YAML is malformed. After receiving the model response, the harness must perform several validation steps before applying any changes. First, parse the corrected_compose field as YAML and verify it is structurally valid. Second, diff the original and corrected compose files to confirm that the changes array accurately reflects every modification. Third, run a port conflict check: extract all host-port mappings from the corrected compose and verify no two services bind to the same host port. Fourth, validate volume mount paths exist on the host filesystem or are defined as named volumes within the compose file. If any validation step fails, log the failure, increment a retry counter, and re-invoke the prompt with the validation error message appended to the [INPUT] context. Set a maximum of three retry attempts before escalating to a human operator.

For production deployments, integrate this prompt into your CI pipeline as a pre-apply safety check rather than an automatic fixer. When the prompt produces a corrected_compose with requires_manual_review set to true, the harness must block the pipeline and post the proposed changes to a review queue—never auto-apply fixes that involve network configuration, security-sensitive volume mounts, or privilege escalations. Log every prompt invocation, including the original error, the model's diagnosis, the proposed changes, validation results, and the final disposition (applied, rejected, or escalated). Use structured logging with trace IDs that link the compose file hash, the error signature, and the prompt response for post-incident analysis. Choose a model with strong YAML generation and instruction-following capabilities; smaller models often introduce subtle YAML indentation errors or omit required service keys, so prefer models with proven structured output reliability for this workflow.