# TROUBLESHOOTING.md

> Guía de problemas comunes y sus soluciones

---

## Dashboard Streamlit

### TS-001: Dashboard muestra fondo negro / tema oscuro

**Síntomas:**
- Texto no visible sobre fondo negro
- Elementos UI con colores incorrectos

**Causa:**
Streamlit usa tema oscuro por defecto basado en preferencias del sistema.

**Solución:**
Crear `.streamlit/config.toml`:
```toml
[theme]
base = "light"
primaryColor = "#6D84E3"
backgroundColor = "#FFFFFF"
secondaryBackgroundColor = "#F8F8F8"
textColor = "#000000"
```

---

### TS-002: Puerto en uso al lanzar Streamlit

**Síntomas:**
```
Error: Address already in use
Port 8501 is in use by another program
```

**Causa:**
Otra instancia de Streamlit o aplicación usando el puerto.

**Solución:**
1. Usar puerto alternativo en `.streamlit/config.toml`:
```toml
[server]
port = 8510
```

2. O especificar en línea de comandos:
```bash
python -m streamlit run dashboard/app.py --server.port 8510
```

---

### TS-003: Plotly ValueError: Invalid property 'titlefont'

**Síntomas:**
```
ValueError: Invalid property specified for object of type plotly.graph_objs.heatmap.ColorBar: 'titlefont'
```

**Causa:**
Plotly deprecó `titlefont` en versiones recientes. Ahora debe usarse estructura anidada.

**Solución:**
```python
# Antes (deprecated)
colorbar=dict(
    title="Label",
    titlefont=dict(size=12),
)

# Ahora (correcto)
colorbar=dict(
    title=dict(text="Label", font=dict(size=12)),
)
```

---

### TS-004: Streamlit 'use_container_width' deprecation warning

**Síntomas:**
```
Please replace `use_container_width` with `width`.
`use_container_width` will be removed after 2025-12-31.
```

**Causa:**
Streamlit cambió la API de `st.dataframe()` y `st.plotly_chart()`.

**Solución:**
```python
# Antes
st.dataframe(df, use_container_width=True)

# Después
st.dataframe(df, width='stretch')
```

**Nota:** Este warning no rompe funcionalidad actualmente.

---

### TS-005: No batch data found

**Síntomas:**
Dashboard muestra "No batch data found" y no carga.

**Causa:**
No hay datos de análisis en `data/output/`.

**Solución:**
1. Ejecutar pipeline primero:
```bash
python cli.py run my_batch -i data/audio -o data/output
```

2. Verificar que existe `data/output/<batch_id>/summary.json`

---

## Pipeline de Análisis

### TS-006: AssemblyAI transcription falla

**Síntomas:**
```
Error: AssemblyAI API error: ...
```

**Soluciones:**
1. Verificar `ASSEMBLYAI_API_KEY` en `.env`
2. Verificar formato de audio (soporta: mp3, wav, m4a, flac)
3. Verificar conectividad a internet

---

### TS-007: OpenAI JSON parsing error

**Síntomas:**
```
Error: Failed to parse JSON response
```

**Causa:**
LLM generó JSON malformado.

**Solución:**
1. El sistema tiene auto-repair built-in
2. Si persiste, usar `--model gpt-4o` (más robusto)
3. Verificar que transcript no está vacío

---

### TS-008: Pipeline resume no funciona

**Síntomas:**
Pipeline reprocesa llamadas ya completadas.

**Causa:**
Manifest corrupto o eliminado.

**Solución:**
1. Verificar `data/output/<batch>/manifests/*.json`
2. Si corrupto, usar `--no-resume` para empezar de cero
3. No eliminar archivos de manifest manualmente

---

## Problemas de Datos

### TS-009: FCR rate muestra 0% cuando hay llamadas

**Causa:**
El campo `fcr_status` no está siendo llenado por el LLM.

**Solución:**
1. Usar `--no-compression` para dar más contexto al LLM
2. Verificar que prompt v2.0 está activo
3. Revisar que transcripts tienen suficiente información

---

### TS-010: Drivers vacíos en análisis

**Síntomas:**
`poor_cx_drivers: []` en todos los análisis.

**Causa:**
- Transcripts muy cortos
- Compresión eliminó información clave
- LLM no encontró evidencia

**Solución:**
1. Usar `--no-compression`
2. Verificar calidad de transcripts
3. Revisar logs para errores de LLM

---

**Última actualización**: 2026-01-19