BeyondCX_Insights/docs/TROUBLESHOOTING.md

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:

[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:

[server]
port = 8510

2. O especificar en línea de comandos:

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:

# 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:

# 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:

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