docker-troubleshoot

Diagnose Docker container failures and apply YAML-based fixes.

35|11|Updated Dec 3, 2025

Search Tags:#troubleshooting #logs #docker #ports

Ready to run

npx skills add https://github.com/mwguerra/claude-code-plugins --skill docker-troubleshoot

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: docker-troubleshoot
Source: https://github.com/mwguerra/claude-code-plugins/tree/main/docker-specialist/skills/docker-troubleshoot
Command: npx skills add https://github.com/mwguerra/claude-code-plugins --skill docker-troubleshoot

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill provides a practical guide to diagnosing and fixing common Docker startup, networking, and permission issues.

Core Features & Use Cases

Logs and configuration checks
Port conflict resolution
Permissions and volume troubleshooting

Quick Start

Diagnose a port conflict and propose steps to resolve.

Frequently Asked Questions about docker-troubleshoot

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I diagnose why my Docker container fails to start?▼

Docker container startup failures stem from configuration errors, permission issues, or resource conflicts. Use Docker logs and inspect commands to review error messages, then check your YAML configuration, volume permissions, and port availability to identify and resolve the root cause.

How do I fix Docker port conflicts?▼

Port conflicts occur when multiple containers or services bind to the same port. Inspect running containers to identify which process occupies the port, then either reassign the conflicting service to a different port in your Docker Compose configuration or stop the competing container.

What should I check when Docker networking between containers isn't working?▼

Docker networking issues typically involve DNS resolution, service discovery, or network isolation. Inspect container logs, verify service names in your Docker Compose configuration, check network connectivity between containers, and confirm firewall rules and container network settings align with your deployment topology.

How do I troubleshoot Docker volume and persistence problems?▼

Volume issues prevent data persistence across container restarts. Verify volume mount paths in your YAML configuration match actual directories, check file permissions for read/write access, and inspect mounted volumes to confirm data is being written to the correct locations.

Why is my Docker health check failing?▼

Health check failures indicate containers aren't responding to liveness probes. Review health check configuration in your Docker Compose file, inspect container logs for startup delays or dependency issues, and verify the health check endpoint or command is accessible and returns expected responses.

Can I use this to troubleshoot Docker Compose and standalone Docker deployments?▼

Yes, this Skill covers both Docker Compose and standalone Docker deployments. It handles startup failures, networking problems, permission errors, and port conflicts across both deployment models, requiring Docker CLI access and read/write permissions to configuration files.