---
name: easypanel-troubleshoot
description: >
  Automated diagnostics for EasyPanel deployment issues via API oficial. Analyzes container logs,
  health endpoints, Traefik routing, and resources to identify root causes.
  Use when user mentions "easypanel troubleshoot", "deploy failed", "502 error",
  "crash loop", "container problems", "debug deployment".
author: Descomplicar® Crescimento Digital
version: 2.0.0
quality_score: 70
user_invocable: true
desk_task: TBD
allowed-tools: Bash, Read
dependencies:
  - easypanel-api
---

# EasyPanel Troubleshoot

Diagnóstico automático e inteligente de problemas de deploy no EasyPanel.

## Quando Usar

- Deploy falhou com erros 502/503
- Container em crash loop (restarts frequentes)
- Health endpoint não responde
- Problemas de routing Traefik
- Investigar causa de deploy falhado
- After deploy validation

## Quando NÃO Usar

- Para deploys iniciais (usar `/easypanel-init`)
- Para rollbacks de versão (usar `/easypanel-rollback`)
- Para validação pós-deploy bem-sucedido (usar `/easypanel-validate`)
- Quando o problema é conhecido e a solução já está identificada

## Sintaxe

```bash
/easypanel-troubleshoot <service-name> [--verbose]
```

## Exemplos

```bash
# Diagnóstico básico
/easypanel-troubleshoot dashboard-api

# Diagnóstico detalhado (logs completos)
/easypanel-troubleshoot dashboard-api --verbose
```

## Workflow Automático

### 1. Check Service Status via API

```bash
# Obter token
TOKEN=$(cat /etc/easypanel/.api-token)

# Inspeccionar serviço (estado completo)
curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=$(echo -n '{"json":{"projectName":"PROJECT","serviceName":"SERVICE"}}' | jq -sRr @uri)" \
  -H "Authorization: Bearer $TOKEN" | jq '.result.data.json'

# Obter logs via API
curl -s "http://localhost:3000/api/trpc/services.app.getServiceLogs?input=$(echo -n '{"json":{"projectName":"PROJECT","serviceName":"SERVICE","lines":100}}' | jq -sRr @uri)" \
  -H "Authorization: Bearer $TOKEN"
```

### 2. Fetch Logs (alternativa SSH)
```bash
docker logs <container> --tail 100
```

Parse de erros comuns:
- Port already in use (EADDRINUSE)
- Cannot find module (dependencies)
- Connection refused (database)
- Out of memory (OOM)
- Unhandled promise rejection
- Listen errors

### 3. Check Health Endpoint
```bash
curl https://<domain>/health
```
- Status code: 200, 404, 502, 503?
- Response time
- Response body validation

### 4. Check Traefik Routing
- Traefik labels correctos?
  - router.rule com domain
  - service.loadbalancer.server.port
  - entrypoints=websecure
  - certresolver=letsencrypt
- Domain DNS aponta para servidor?
- SSL certificate válido?

### 5. Check Port Mismatch
- Dockerfile EXPOSE vs app actual port
- docker-compose ports vs Traefik port
- App listening port (from logs)
- Common mismatch: 3000 vs 8080

### 6. Check Environment Variables
- Required vars set? (compare .env.example)
- Sensitive vars (DATABASE_URL, API_KEY)
- Missing vars causing app crash?

### 7. Check Dependencies
- Database reachable? (if applicable)
- Redis reachable? (if applicable)
- External APIs responding?

### 8. Check Resources
- CPU throttling?
- Memory limit reached (OOM)?
- Disk space?

### 9. Generate Report
- Issues found (prioritized: CRITICAL, WARNING, INFO)
- Root cause (if detected)
- Recommended fixes (step-by-step)
- Commands to run

## Error Pattern Detection

### Port Mismatch
```
Pattern: "listening on port X" + Traefik port Y
Fix: Update Dockerfile EXPOSE or Traefik label
```

### Missing Environment Variable
```
Pattern: "is not defined" / "undefined"
Fix: Add variable to EasyPanel environment
```

### Crash Loop
```
Pattern: Restart count > 3 in 10min
Fix: Check logs for root cause
```

### Database Connection
```
Pattern: "ECONNREFUSED" / "Connection refused"
Fix: Verify DATABASE_URL and network connectivity
```

### Memory Issues
```
Pattern: "out of memory" / "OOM killed"
Fix: Increase memory limit in docker-compose
```

## Output Format

```
🔍 EasyPanel Troubleshooting: <service-name>

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 SERVICE STATUS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Container: <name>
Status: Running | Stopped | Restarting
Uptime: <time>
Restarts: <count> (last 10min)
Memory: X / Y MB
CPU: X%

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 ISSUES FOUND (X)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. 🔴 CRITICAL: <Issue Title>
   Detected: <details>
   Impact: <what breaks>

   Fix:
   <step-by-step solution>

2. ⚠️  WARNING: <Issue Title>
   ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 LOGS (Last 20 lines)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[timestamp] INFO: ...
[timestamp] ❌ ERROR: ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🛠️  RECOMMENDED ACTIONS (Prioritized)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. <Action 1>
2. <Action 2>
3. Redeploy: git commit + push

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔗 HELPFUL RESOURCES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- Research: /media/ealmeida/Dados/Dev/Docs/EasyPanel-Deploy-Research/
- Checklist: CHECKLIST_EasyPanel_Deploy.md
- Templates: TEMPLATE_Dockerfile_NodeJS_MultiStage
```

## API Endpoints Usados

Ver skill `/easypanel-api` para documentação completa.

| Acção | Endpoint |
|-------|----------|
| Estado serviço | `GET services.app.inspectService` |
| Logs serviço | `GET services.app.getServiceLogs` |
| Listar projectos | `GET projects.listProjects` |
| Estatísticas monitor | `GET monitor.getStats` |

## MCPs Necessários

- ✅ `ssh-unified` - Acesso ao servidor para API e fallback

## Tools Necessários

```bash
# Via SSH
docker ps
docker logs <container> --tail 100
docker inspect <container>
curl https://<domain>/health
```

## Checklist Execução

- [ ] Conectar via SSH ao servidor EasyPanel
- [ ] Obter status do container (docker ps)
- [ ] Fetch logs (últimas 100 linhas)
- [ ] Parse errors automático (patterns conhecidos)
- [ ] Check health endpoint (curl)
- [ ] Verificar Traefik labels (docker inspect)
- [ ] Detectar port mismatch
- [ ] Verificar env vars (se possível)
- [ ] Gerar report estruturado
- [ ] Recomendar fixes priorizados

## Error Messages Database

### Common Patterns

| Pattern | Root Cause | Fix |
|---------|------------|-----|
| `EADDRINUSE :::PORT` | Port já em uso | Matar processo ou usar porta diferente |
| `Cannot find module 'X'` | Dependency missing | npm install no build |
| `ECONNREFUSED` | Database/service down | Verificar network/DATABASE_URL |
| `502 Bad Gateway` | App crash ou port mismatch | Check logs + ports |
| `MODULE_NOT_FOUND` | Build incorrecto | Verificar Dockerfile COPY |
| `OOM killed` | Memória insuficiente | Aumentar limite RAM |

## Security

- NUNCA expor credenciais nos logs
- Sanitizar env vars em output
- Limitar acesso SSH apenas ao necessário

## Performance

- Limitar logs a 100 linhas (evitar overflow)
- Cache de patterns conhecidos
- Timeout de 30s em curl health checks

---

**Versão:** 1.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-04

## Metadata (Desk CRM Task #65)

```
Tarefa: SKL: /easypanel-troubleshoot - Automated Diagnostics
Milestone: 294 (Skills Claude Code)
Tags: skill(79), stackworkflow(75), claude-code(81), activo(116)
Responsáveis: Emanuel(1), AikTop(25)
Status: 4 (Em progresso) → 5 (Concluído)
```

---

**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/