From acc
Analyzes Docker runtime errors in PHP containers, diagnosing 502 Bad Gateway, OOM kills, connection refused, permission denied, segfaults, and pool exhaustion with targeted fixes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/acc:analyze-docker-runtime-errorsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Analyze running PHP containers for runtime failures and provide targeted diagnosis and fixes.
Analyze running PHP containers for runtime failures and provide targeted diagnosis and fixes.
| Error | Symptom | Root Cause |
|---|---|---|
| 502 Bad Gateway | Nginx returns 502 | PHP-FPM not running or crashed |
| OOM Killed | Container restarts | memory_limit or container limit exceeded |
| Connection refused | Service unreachable | Container not ready or wrong network |
| Permission denied | File operation fails | UID/GID mismatch or read-only fs |
| Segmentation fault | Process crashes | Extension bug or memory corruption |
| Slow requests | Timeouts, 504 errors | PHP-FPM pool exhaustion |
# FIX: Add healthcheck and proper depends_on
services:
php-fpm:
healthcheck:
test: ["CMD-SHELL", "php-fpm-healthcheck || exit 1"]
interval: 10s
timeout: 5s
retries: 3
nginx:
depends_on:
php-fpm:
condition: service_healthy
; php.ini -- match memory_limit to container limit
; Container limit 256MB -> PHP memory_limit should be lower
memory_limit = 128M
# docker-compose.yml memory constraints
services:
php-fpm:
deploy:
resources:
limits:
memory: 512M
reservations:
memory: 256M
# FIX: Proper service dependencies and networking
services:
php-fpm:
depends_on:
redis: { condition: service_healthy }
database: { condition: service_healthy }
networks: [app-network]
redis:
healthcheck:
test: ["CMD", "redis-cli", "ping"]
networks: [app-network]
database:
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER"]
networks: [app-network]
networks:
app-network:
driver: bridge
# FIX: Set correct ownership in Dockerfile
RUN mkdir -p /var/www/var/cache /var/www/var/log \
&& chown -R www-data:www-data /var/www/var
COPY --chown=www-data:www-data . /var/www
USER www-data
; Sizing formula: max_children = (available_memory - overhead) / avg_process_memory
; Example: (512MB - 64MB) / 32MB = ~14
[www]
pm = dynamic
pm.max_children = 14
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6
pm.max_requests = 500
; Mitigation: disable problematic extensions one by one
; Common cause: OPcache + Xdebug conflict
opcache.enable=0 ; Test if OPcache causes segfault
opcache.fast_shutdown=0
# Find PHP-FPM configuration
Grep: "pm\.(max_children|start_servers|max_requests)" --glob "**/www.conf" --glob "**/php-fpm*.conf"
# Find memory_limit settings
Grep: "memory_limit" --glob "**/php.ini" --glob "**/*.ini"
# Find healthcheck definitions
Grep: "healthcheck" --glob "**/docker-compose*.yml"
# Find depends_on without condition
Grep: "depends_on:" --glob "**/docker-compose*.yml"
# Find error logging configuration
Grep: "error_log|log_errors" --glob "**/php.ini" --glob "**/*.ini"
| Log Pattern | Diagnosis | Fix |
|---|---|---|
server reached pm.max_children | Pool exhaustion | Increase max_children or optimize code |
child exited on signal 11 | Segmentation fault | Check extensions, disable OPcache |
child exited with code 255 | Fatal PHP error | Check error log for details |
execution timed out | Slow script | Profile code, check DB queries |
unable to open primary script | Wrong document root | Fix Nginx fastcgi_param SCRIPT_FILENAME |
| Pattern | Severity | Impact |
|---|---|---|
| OOM Killed (recurring) | Critical | Service unavailable, data loss risk |
| PHP-FPM pool exhaustion | Critical | All requests blocked |
| Segmentation fault | Critical | Process crash, intermittent failures |
| 502 Bad Gateway | Major | Service unavailable |
| Connection refused | Major | Dependent service failures |
| Permission denied (runtime) | Major | Feature degradation |
| Slow requests (< threshold) | Minor | User experience impact |
### Runtime Error: [Category]
**Severity:** Critical/Major/Minor
**Container:** `<service_name>`
**Log Pattern:** `<error message from logs>`
**Diagnosis:**
[Root cause analysis with evidence from logs]
**Steps to Verify:**
1. [Command to confirm the issue]
2. [Command to check related state]
**Fix:**
```yaml
# docker-compose.yml or config change
Monitoring: [How to detect this issue early in production]
npx claudepluginhub dykyi-roman/awesome-claude-code --plugin accProvides solutions for common Docker build and runtime errors in PHP containers (e.g., OOM, permission denied, PHP-FPM crashes) plus diagnostic bash commands for logs, inspection, and stats.
Diagnoses Docker container failures, networking issues, permissions errors, port conflicts, data persistence problems, and health checks using docker compose logs, inspect, and targeted fixes.