Cuando explota: los 7 errores de servir vLLM en GPU alquilada

Tu servidor va a fallar. No es pesimismo, es estadística: alquilaste un contenedor efímero, descargaste 31 GB de pesos y levantaste tres servicios que se conocieron hoy. La diferencia entre perder 10 minutos y perder una tarde es conocer los síntomas.

Estos 7 errores me pasaron a mí, en un entorno real, sirviendo el modelo de esta guía. Cada uno va con su mensaje de error exacto, su causa y su fix, para que la próxima vez el diagnóstico dure minutos.

1. Operation not permitted (os error 1) al instalar

Síntoma: la instalación de vLLM o cualquier chmod revienta con ese error.

Causa: instalaste en el volumen de red (/workspace). Los volúmenes de red no soportan operaciones POSIX como chmod.

Fix: binarios y venvs al container disk (/root/venv-vllm), cachés incluidas (UV_CACHE_DIR=/root/.cache/uv). Pesos al volumen. La regla completa está en el capítulo 3.

2. config.json is not a valid JSON (o pesos en 0 bytes)

Síntoma: la descarga "termina" pero el modelo no carga, o el error menciona JSON inválido.

Causa: el volumen de red no conserva los symlinks que la caché de Hugging Face usa internamente. Algunos archivos quedaron como enlaces rotos o vacíos.

Fix: descarga de nuevo con la CLI moderna (hf download ...) verificando con du -sh que pesa lo esperado (~31 GB en nuestro caso). Si tu versión de la CLI te lo permite, descarga a una carpeta plana con --local-dir.

3. vLLM muere al arrancar sin motivo aparente

Síntoma: vllm serve arranca y se cae, o un arranque nuevo falla con errores de memoria raros.

Causa: un proceso huérfano VLLM::EngineCore de un intento anterior sigue reteniendo la VRAM. El pod es un contenedor: cuando matas el proceso padre, a veces el hijo sobrevive.

Fix:

# terminal del pod
pkill -9 -f VLLM::EngineCore
nvidia-smi    # hasta ver 0 MiB usados

No relances hasta que nvidia-smi muestre la VRAM libre. Relanzar encima de un zombie es la receta para un OOM confuso.

4. address already in use en el puerto 8000 o 4000

Síntoma: el servicio no arranca porque el puerto está ocupado.

Causa: casi siempre es el Jupyter del template (8888 no, pero si reasignaste) o un LiteLLM viejo que no moriste bien.

Fix: identifica y mata el proceso del puerto. Y si el puerto que falta ni siquiera está expuesto, es el error del capítulo 3: los puertos se declaran al crear el pod.

5. /key/generate responde Not Found

Síntoma: LiteLLM corre, pero crear keys devuelve 404.

Causa: LiteLLM arrancó sin capa de base de datos (capítulo 7, paso 1), o el virtual key endpoint no existe porque instalaste el paquete base.

Fix: instala el extra completo (litellm[proxy,extra_proxy]), verifica service postgresql status y que DATABASE_URL esté exportada antes de arrancar.

6. prisma-client-py: not found en LiteLLM

Síntoma: LiteLLM no arranca quejándose de Prisma.

Causa: el cliente de Prisma se generó con una ruta absoluta del momento de la instalación.

Fix: exporta el venv al PATH antes de arrancar: export PATH=/root/venv-litellm/bin:$PATH. Es el mismo venv que activaste, pero LiteLLM lanza subprocessos que no heredan la activación.

7. La UI de LiteLLM se ve morida (vacía o redirigiendo a una IP interna)

Síntoma: la UI carga en morido o intenta redirigir a una IP que no es la tuya.

Causa: el proxy de RunPod sirve el pod bajo otro host, y LiteLLM genera URLs con su host interno sin confiar en el proxy.

Fix: ajusta el asset prefix (/litellm-asset-prefix) y exporta FORWARDED_ALLOW_IPS='*' antes de arrancar el gateway.

Bonus: los dos errores de memoria y hardware

El método general de diagnóstico

Detrás de los 7 hay un método que vale más que los fixes:

1. El log primero. tail -f /workspace/vllm.log antes de tocar nada. El 80% de las respuestas están escritas ahí.
2. nvidia-smi siempre. VRAM en 0 cuando crees que todo murió es la firma del proceso zombie.
3. Un cambio por vez. Si cambias tres cosas y funciona, no sabes cuál era. Si cambias tres y rompes, tampoco.
4. Anota el síntoma exacto. El mensaje de error textual es lo que te salva la próxima vez. Mi lista de 7 se convirtió en un runbook, en un script de arranque idempotente y en dos posts.

Checkpoint: tu propio runbook.md con los síntomas que TÚ ya viste. Empieza hoy, con este capítulo como semilla.

El error típico de este nivel: re-desplegar a ciegas (destruir el pod y empezar de cero) en cuanto algo falla. A veces es lo correcto (la nube es desechable), pero destruir sin anotar la causa es comprar la misma lección dos veces.

Cierre de la guía

Llegaste al final: entendiste qué es servir un modelo, corriste uno local, alquilaste GPU, encendiste vLLM, configuraste sus flags, mediste con números reales, pusiste un gateway con llaves y presupuestos, y sobreviviste a los errores. Eso es, en pequeño, el trabajo diario de un inference engineer.

Los posts de mi PoC real profundizan cada medición: empieza por El plan: servir mi propio modelo para bajar la factura y sigue la serie completa desde ahí.

¿Qué error te tocó a ti que no está en la lista? Déjalo en los comentarios: este capítulo se actualiza con los casos de los lectores.

---