Saltar al contenido
Kevin Davila mascotkevindavila.dev> SOFTWARE ENGINEEREN
AI•3 min de lectura

Los 7 bugs del entorno alquilado

El primer intento de levantar el servidor falló tres veces seguidas, por tres causas distintas, ninguna relacionada con el modelo. Al final de la semana teníamos una lista de siete bugs que no son de vLLM ni de LiteLLM: son del entorno alquilado (volumen de red, contenedores, puertos). Los dejo aquí porque cuestan horas y no aparecen en ningún tutorial.

1. Operation not permitted al instalar o dar permisos

Síntoma: uv pip install o chmod fallan con permiso denegado aunque estés como root.

Causa: el volumen de red del pod no soporta chmod (no es un filesystem POSIX completo).

Fix: todo lo que necesite permisos va al disco del contenedor, no al volumen:

# venvs y binarios en el disco del contenedor
/root/venv-vllm/bin/python ...
# datos y pesos en el volumen (sobrevive al apagado)
/workspace/models/...

La regla: el volumen guarda datos; el contenedor guarda programas.

2. config.json is not a valid JSON y pesos en 0 bytes

Síntoma: la descarga del modelo "termina", pero al cargar vLLM dice que config.json no es JSON válido y varios archivos pesan 0 bytes.

Causa: el volumen de red no conserva los symlinks que usa la caché de Hugging Face (los blobs reales están en un directorio y el resto son enlaces).

Fix: descargar con --local-dir para obtener una carpeta plana sin symlinks:

hf download Qwen/Qwen3-Coder-30B-A3B-Instruct-FP8 \
  --local-dir /workspace/models/qwen3-coder-30b

3. vLLM muere al arrancar sin motivo

Síntoma: vllm serve se cae con un error genérico de memoria, incluso con los pesos bien descargados.

Causa: un proceso VLLM::EngineCore huérfano de un intento anterior seguía reteniendo la VRAM.

Fix: matarlo y confirmar que la GPU está limpia antes de relanzar:

pkill -9 -f "VLLM::EngineCore"
nvidia-smi --query-gpu=memory.used --format=csv   # debe decir 0 MiB

Si no confirmas el 0 MiB, el siguiente arranque falla otra vez y crees que el bug es del modelo.

4. address already in use

Síntoma: el gateway no arranca; el puerto (8888 en nuestro caso) está ocupado.

Causa: un Jupyter o un LiteLLM viejo seguía vivo en ese puerto.

Fix: identificar y matar el proceso del puerto:

lsof -i :8888
kill -9 <PID>

5. /key/generate devuelve Not Found

Síntoma: la UI de LiteLLM funciona, pero crear una key virtual falla con 404.

Causa: LiteLLM sin la capa de base de datos: sin Postgres, los endpoints de gestión de keys no existen.

Fix: instalar con los extras y generar el cliente de Prisma:

uv pip install "litellm[proxy,extra_proxy]"
prisma generate

6. prisma-client-py: not found

Síntoma: el paso anterior falla porque no encuentra prisma.

Causa: Prisma se había generado con una ruta absoluta y el binario no estaba en el PATH.

Fix:

export PATH=/root/venv-litellm/bin:$PATH

7. La UI morada y vacía, o redirigida a una IP interna

Síntoma: abres la UI del gateway a través del proxy y sale morada o sin datos, con redirecciones a una IP que no existe.

Causa: el placeholder de assets (/litellm-asset-prefix) mal configurado y uvicorn sin confiar en el proxy.

Fix: ajustar el prefijo y permitir los forwarded headers:

export FORWARDED_ALLOW_IPS='*'
# y en la config del gateway: asset prefix -> /ui

Lo que esto enseña (más allá de los 7 fixes)

  1. El entorno alquilado tiene reglas propias. vLLM y LiteLLM son la parte fácil; el volumen de red, los puertos y los procesos zombis son la parte que nadie documenta.
  2. Documenta los bugs el mismo día. Esta lista salió de un archivo de troubleshooting que fuimos llenando en caliente; si la escribes al final, se te olvidan.
  3. Los tiempos también cuentan. Levantar el stack completo (Postgres → vLLM → gateway → keys) tardó 12-15 minutos; la primera descarga del modelo, ~10 minutos; cada arranque de vLLM, 3-6 minutos. En un PoC eso es ruido; en producción es el dato que decide si usas serverless o una instancia siempre encendida.
  4. Un bug silencioso te hace culpar al modelo. El EngineCore huérfano (bug 3) parece "el modelo no cabe"; la descarga con symlinks rotos (bug 2) parece "el modelo está corrupto". Casi nunca es el modelo.

El runbook completo, con los scripts de arranque y parada, está en el repo del PoC. Y el marco general, en la guía Inference Engineering.

¿Cuál es el bug de entorno que más horas te ha costado? Cuéntame en los comentarios: casi siempre es de los que no aparecen en Google.

Referencias

> Más posts