> For the complete documentation index, see [llms.txt](https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/operacion-y-monitoreo/troubleshooting.md).

# Solución de problemas

Guía de los errores más frecuentes al operar Taína y cómo resolverlos.

## Problemas de arranque

### El contenedor no arranca

```bash
# Ver logs detallados
docker compose logs taina-backend
```

**Causas y soluciones comunes:**

| Error en logs               | Solución                                                                                        |
| --------------------------- | ----------------------------------------------------------------------------------------------- |
| `"API key not found"`       | Verifica tu archivo `backend/.env` y reconstruye: `docker compose up -d --build`                |
| `"port already in use"`     | Otro servicio usa el puerto 8080. Detén ese servicio o cambia el puerto en `docker-compose.yml` |
| `"no space left on device"` | Libera espacio en disco: `docker system prune -a`                                               |

### Error: `ModuleNotFoundError: No module named 'src'`

Esto no debería ocurrir con Docker. Si ejecutas fuera de Docker:

```bash
# Asegúrate de estar en el directorio backend
cd taina_ogtic/backend

# Para ejecución local, configura PYTHONPATH
export PYTHONPATH=$(pwd)
```

### Error: `ValueError: Collection 'servicios' not found`

La base de conocimiento no se ha construido:

```bash
# Verificar que existen archivos en data/chunks/
ls backend/data/chunks/*.json

# Ejecutar ingesta
docker compose exec taina-backend python -m src.ingest --json_dir data/chunks

# Verificar la colección
docker compose exec taina-backend python3 -c "
import chromadb
c = chromadb.PersistentClient(path='storage/chroma')
print([col.name for col in c.list_collections()])
"
```

### API keys no detectadas

```bash
# Verificar variables dentro del contenedor
docker compose exec taina-backend python3 -c "
import os
from dotenv import load_dotenv
load_dotenv()

for var in ['LIVEKIT_URL', 'GOOGLE_API_KEY', 'DEEPGRAM_API_KEY', 'ELEVENLABS_API_KEY']:
    value = os.getenv(var)
    print(f'{var}: {\"✅ SET\" if value else \"❌ NOT SET\"}')
"
```

Si una variable falta, edita `backend/.env` y reconstruye:

```bash
docker compose up -d --build
```

## Problemas de conexión

### LiveKit

* Valida `LIVEKIT_URL`, `LIVEKIT_API_KEY` y `LIVEKIT_API_SECRET` en tu `.env`.
* Las claves deben corresponder al clúster correcto (producción o desarrollo).

### Google Gemini

* Revisa cuotas en [Google Cloud Console](https://console.cloud.google.com/) si recibes `QuotaExceededError`.
* El sistema tiene backoff exponencial integrado, pero si persiste, espera y vuelve a intentar.

### Deepgram / ElevenLabs

* Confirma que los tokens estén activos verificando en sus respectivas consolas web.

### No se escucha audio en LiveKit

Verifica que los modelos de IA locales se descargaron durante el build:

```bash
docker compose logs taina-backend | grep -i "download\|model\|VAD"
```

Si no se descargaron, reconstruye la imagen:

```bash
docker compose up -d --build
```

## Problemas de rendimiento

### Uso de memoria elevado

```bash
# Ver consumo actual
docker stats taina_backend

# Ajustar límites en .env
# MAX_MEMORY_MB=2500
# WARNING_MEMORY_MB=1800
# WORKER_PROCESSES=2  (reducir en entornos limitados)
```

### Timeouts recurrentes

Ajusta los timeouts en `.env`:

```ini
STT_TIMEOUT=30
LLM_TIMEOUT=45
TTS_TIMEOUT=20
```

Habilita `ENABLE_AUTO_RECOVERY=true` para reinicios controlados.

## ChromaDB

### Base vacía o corrupta

```bash
# Verificar colección
docker compose exec taina-backend python3 -c "
import chromadb
client = chromadb.PersistentClient(path='storage/chroma')
col = client.get_collection('servicios')
print(f'Documentos: {col.count()}')
"

# Si está vacía, ejecutar ingesta
docker compose exec taina-backend python -m src.ingest --json_dir data/chunks
```

### Reiniciar ChromaDB desde cero

```bash
# Detener el servicio
docker compose down

# Limpiar storage
rm -rf backend/storage/chroma/
rm -rf backend/storage/chroma_qa/

# Reconstruir
docker compose up -d --build

# Ejecutar ingesta
docker compose exec taina-backend python -m src.ingest --json_dir data/chunks
```

## Logs del sistema

```bash
# Logs en tiempo real
docker compose logs -f taina-backend

# Últimas 100 líneas
docker compose logs --tail=100 taina-backend

# Logs desde el host (volumen montado)
tail -f backend/logs/application.log
tail -f backend/logs/errors.log
```

## Limpiar y empezar de cero

```bash
# Detener y eliminar contenedores, volúmenes e imágenes
docker compose down --volumes --rmi all

# Reconstruir todo
docker compose up -d --build
```

## Recursos

* [Variables de entorno](/taina-agente-ia-ogtic/empezando-con-taina/configuracion-entorno.md)
* [Base de conocimiento](/taina-agente-ia-ogtic/empezando-con-taina/base-conocimiento.md)
* [Monitoreo](/taina-agente-ia-ogtic/operacion-y-monitoreo/monitoreo.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/operacion-y-monitoreo/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.