Saltar al contenido principal

Solución de problemas

Empieza siempre aquí:

docker logs --tail 50 neurogrid-agent

El agente se detuvo después de que cambié de red​

Síntoma. Los heartbeats funcionaban bien, y de repente todos fallan. O un trabajo carga el modelo y luego muere al abrir su túnel, siempre después de más o menos la misma cantidad de segundos. Tu internet funciona bien en todo lo demás.

Causa. Docker le da a un contenedor su configuración de DNS cuando el contenedor se crea, y nunca la actualiza. Mueve la máquina a una red distinta — una laptop que deja un hotspot, un nuevo lease de DHCP, un cambio de router — y el contenedor sigue preguntándole a un resolutor que ya no existe. El enrutamiento sigue funcionando, así que nada parece desconectado: solo fallan los nombres, cada uno colgado hasta que expira.

Arreglo. Reconectar el Wi-Fi no ayuda. Recrea el contenedor, o simplemente reinícialo:

docker restart neurogrid-agent

El agente lo dice él mismo cuando pasa esto — busca Cannot resolve the backend's hostname en los logs.

Prevención. Instala con --dns 1.1.1.1 --dns 8.8.8.8, como en las instrucciones de Linux y Windows. Esos resolutores existen en cualquier red, así que al contenedor deja de importarle en cuál está la máquina.

nvidia-smi funciona en el host pero no en Docker​

Falta el NVIDIA Container Toolkit o el daemon no lo ha detectado.

# Linux
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

En Windows, esto suele significar que Docker Desktop no está en el backend de WSL2, o que el driver de Windows es más viejo que 575.

El registro falla con un token inválido​

El log dice que el backend no reconoce el token. Casi siempre es uno de estos:

  • Se truncó al copiarlo. Los tokens de máquina son largos; copia la cadena completa.
  • Ya fue usado por otra máquina. Un token reclama una sola GPU. Consigue uno nuevo desde la consola.
  • El listado fue cancelado en la consola antes de que el agente se registrara.

Dice que el archivo de configuración es escribible y se niega a iniciar​

A propósito. Ese archivo define con qué servidor habla el agente, así que cualquiera que pueda escribirlo puede redirigir tu máquina y quedarse con su trabajo.

docker exec neurogrid-agent chmod 600 /data/config/config.yaml
docker restart neurogrid-agent

Los trabajos fallan justo después de que el modelo carga​

Casi siempre es el túnel, y casi siempre es el DNS — ver arriba. Si el DNS está sano, revisa que el HTTPS de salida en el puerto 443 no esté bloqueado; algunas redes corporativas y de campus lo filtran.

El disco se llenó​

Los pesos de los modelos son grandes y la caché crece con cada modelo distinto que sirves.

docker system df                 # a dónde se fue
docker image prune -f            # imágenes sin etiqueta
docker volume rm neurogrid-hf-cache   # la caché de modelos, solo mientras está inactivo

Nunca elimines neurogrid-data — es tu registro.

La GPU aparece desconectada pero el contenedor está corriendo​

El agente está vivo pero sus heartbeats no están llegando. Revisa los logs buscando gRPC error sending heartbeat, y luego:

docker exec neurogrid-agent getent hosts api.neurogrid.cc

Sin salida significa DNS — reinicia el contenedor. Con salida pero igualmente desconectado significa que la conexión se está bloqueando en algún punto entre tú y nosotros.

Un trabajo falló y no sé por qué​

docker logs neurogrid-agent 2>&1 | grep -iE "error|failed"

Los contenedores de trabajo se eliminan cuando terminan, así que sus propios logs ya no están cuando los buscas. El log del agente conserva la razón.

Sigo atascado​

Abre un issue en github.com/NeuroGrid-AI-exchange con la salida de:

docker logs --tail 100 neurogrid-agent
docker inspect neurogrid-agent --format '{{.Config.Image}}'
nvidia-smi --query-gpu=name,driver_version,memory.total --format=csv