Solución de problemas

Empiece aquí: triage por síntoma

Use esta tabla para ir al primer check rápidamente.

¿Necesita definiciones de términos de licencia/scheduler? Vea el Glosario.

Síntoma	Primer check	Ubicación en WebUI	Siguiente sección
No se puede acceder a la WebUI	`systemctl status lqosd caddy`	N/A (UI no disponible)	No hay WebUI en x.x.x.x:9123 o en la URL HTTPS
Hay tráfico pero no hace shaping	verificar `to_internet` / `to_network` y servicios	WebUI Dashboard	LibreQoS está en ejecución, pero no hace shaping
Scheduler no saludable	revisar logs de `lqosd` y `lqos_scheduler`	WebUI -> Scheduler Status	El estado del scheduler en WebUI aparece no saludable
Vistas de topología/flujo vacías	confirmar tráfico reciente y estado de `lqosd`	WebUI -> Flow Globe / Tree / ASN Analysis	Flow Globe / Tree Overview / ASN Analysis aparecen en blanco
Aparece código urgente	abrir detalle y mapear código	WebUI -> Urgent Issues	Códigos de problemas urgentes y primeras acciones
Eventos de límite de circuitos	validar licencia y conteos mapped	Insight UI + WebUI -> Urgent Issues	Se alcanzó el límite de circuitos mapeados

Problemas comunes

Dónde en la WebUI

Estado de servicios y salud general: WebUI -> Dashboard
Estado/readiness del scheduler: WebUI -> Scheduler Status
Alertas prioritarias: WebUI -> Urgent Issues
Visualización de topología/tráfico: WebUI -> Network Tree Overview y Flow Globe
Revisión de datos de shaping: WebUI -> Shaped Devices Editor

Antes de pedir ayuda en chat: recolecte esta evidencia

sudo systemctl status lqosd lqos_scheduler
journalctl -u lqosd --since "30 minutes ago"
journalctl -u lqos_scheduler --since "30 minutes ago"

Si el problema es de integración, agregue:

ls -lh /opt/libreqos/src/topology_import.json /opt/libreqos/src/shaping_inputs.json

Si usa un despliegue manual o con archivos propios en lugar de una integración incluida, agregue:

ls -lh /opt/libreqos/src/network.json /opt/libreqos/src/ShapedDevices.csv

Incluya también:

versión/build actual
tipo de integración y estrategia
síntoma exacto y hora de inicio

La contraseña de usuario no funciona

Los builds actuales:

migran automáticamente archivos de autenticación antiguos
redirigen /login.html a /first-run.html cuando no existen usuarios

sudo systemctl restart lqosd

Si el usuario/contraseña correctos siguen fallando, pruebe primero con ese reinicio.

Elimine lqusers.toml solo si desea reiniciar el acceso o si el archivo está corrupto y no se puede reparar. Después de eliminarlo, reinicie lqosd y abra IP_CAJA:9123/login.html si SSL está deshabilitado; la WebUI debería redirigirlo automáticamente al flujo de primer inicio.

No hay WebUI en x.x.x.x:9123 o en la URL HTTPS

La WebUI depende de lqosd. Si HTTPS opcional con Caddy está habilitado, caddy también debe estar saludable.

sudo systemctl status lqosd caddy

Luego:

Si SSL está deshabilitado, pruebe http://tu-ip-de-gestión:9123/
Si SSL está habilitado con hostname, pruebe https://tu-hostname/
Si SSL está habilitado sin hostname, pruebe https://tu-ip-de-gestión/
Si el navegador advierte en modo de certificado local, confíe en /var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt en la estación de trabajo del operador

Luego siga el flujo completo en El servicio lqosd no se ejecuta o falla al iniciar.

LibreQoS está en ejecución, pero no hace shaping

Verifique en /etc/lqos.conf que to_internet y to_network estén correctos.

sudo systemctl restart lqosd lqos_scheduler
sudo systemctl status lqosd lqos_scheduler

On-a-stick: shaping incorrecto o una dirección débil

On-a-stick depende de split correcto por dirección. Si la detección TX o override_available_queues está mal, el mapeo puede degradarse.

sudo systemctl status lqosd
journalctl -u lqosd --since "10 minutes ago"
sudo systemctl restart lqosd lqos_scheduler

El servicio lqosd no se ejecuta o falla al iniciar

sudo systemctl status lqosd
journalctl -u lqosd --since "10 minutes ago"

Si el log muestra LibreQoS failed to attach the XDP/TC kernel o Unable to load the XDP/TC kernel, trate el arranque de lqosd como fallido. La WebUI y el bus local no arrancan hasta que el programa del kernel se cargue y se adjunte correctamente. El error de carga incluye el valor de retorno bruto, el número errno y el código errno, por ejemplo raw=-11, errno=11, code=EAGAIN. Revise si hay un programa XDP existente, un hook TC ocupado, falta de soporte del driver o mapas BPF fijados obsoletos antes de reiniciar lqosd.

Depuración avanzada de lqosd

sudo RUST_LOG=info /opt/libreqos/src/bin/lqosd

El servicio lqos_scheduler muestra errores

sudo journalctl -u lqos_scheduler --since "1 day ago" --no-pager > lqos_sched_log.txt

Las instalaciones empaquetadas mantienen las dependencias Python de LibreQoS en /opt/libreqos/venv. Los servicios siguen ejecutándose como root, pero los paquetes Python no se mezclan con los paquetes administrados por apt. Si el scheduler informa módulos faltantes, o si la configuración del paquete se interrumpió al instalar dependencias Python, reconstruya el entorno virtual:

sudo /opt/libreqos/src/bin/rebuild_python_venv.sh
sudo dpkg --configure -a
sudo systemctl restart lqosd lqos_scheduler

Las instalaciones basadas en git deben usar ./build_rust.sh después de actualizar. Ese script reconstruye el entorno virtual antes de actualizar los archivos de servicio o reiniciar servicios. Si systemd informa status=203/EXEC en /opt/libreqos/venv/bin/python, o una falla en la comprobación previa del scheduler, reconstruya el entorno virtual con el comando anterior y reinicie lqos_scheduler.

Las instalaciones antiguas anteriores al entorno virtual pueden mostrar ModuleNotFoundError y recomendar comandos de pip del sistema. No repare instalaciones actuales con pip del sistema ni con --break-system-packages; esos paquetes no los usa el servicio lqos_scheduler respaldado por el entorno virtual. Actualice a un paquete que cree /opt/libreqos/venv y use el comando de reparación anterior.

Si el scheduler falla inmediatamente después de un reinicio con un mensaje como Socket (typically /run/lqos/bus) not found, eso indica que lqosd todavía no había terminado de enlazar el bus local. Los builds actuales esperan brevemente la disponibilidad del bus al arrancar el scheduler en lugar de abortar de inmediato, por lo que ya no deberían aparecer panics repetidos de arranque tras un reinicio.

Si journalctl -u lqosd muestra lqosd host memory pressure o lqosd process memory critical, el daemon detectó uso alto de memoria y registró contexto de diagnóstico. El watchdog no reinicia lqosd; registra memoria disponible, memoria total, RSS/swap de lqosd, cantidad de hilos, cantidad de flujos y contadores de tiempo que ayudan a diagnosticar el origen del crecimiento de memoria. La presión de memoria del host se registra cuando la memoria disponible está por debajo del 10% de la RAM instalada. La memoria del proceso se registra como crítica cuando el RSS más swap de lqosd alcanza el 90% de la RAM instalada.

Puede desactivar estos diagnósticos con un override de entorno de systemd durante ventanas cortas de diagnóstico:

sudo systemctl edit lqosd

Use LQOSD_MEMORY_WATCHDOG_DISABLED=1 solamente cuando esté observando activamente la presión de memoria con otra herramienta.

El estado del scheduler en WebUI aparece no saludable

Versiones recientes muestran estado/readiness del scheduler en WebUI. Si el modal del scheduler indica que se agotó el tiempo al cargar detalles, las versiones actuales mantienen visible la última instantánea buena del scheduler con su antigüedad en lugar de convertir ese problema de transporte en un error del scheduler. Trate primero esa advertencia como un problema de comunicación entre WebUI y lqosd, y confirme la salud real del scheduler en los logs antes de asumir que falló el shaping. Si falla un subproceso de integración pero el shaping puede continuar con la última topología válida, el scheduler puede seguir mostrando estado ready, pero el último error de integración permanece visible en el estado del scheduler hasta la siguiente integración exitosa. Si el scheduler no puede leer lqos_overrides.json o sus capas materializadas porque otro proceso mantiene el lock de overrides, las versiones actuales reintentan brevemente y luego bloquean esa recarga. La topología anterior permanece en uso, y el error del scheduler incluye detalles del proceso que mantiene el lock, como PID, nombre de proceso, operación y hora de creación cuando estén disponibles.

Si aparece caído/desactualizado:

Verifique ambos servicios.
Revise logs recientes del scheduler.
Revise logs de lqosd para eventos de scheduler ready/error.
Si hubo cambios recientes, reinicie servicios.

sudo systemctl status lqosd lqos_scheduler
journalctl -u lqos_scheduler --since "30 minutes ago"
journalctl -u lqosd --since "30 minutes ago"
sudo systemctl restart lqosd lqos_scheduler

Si oscila entre ready/error, valide credenciales y timeouts de integración en /etc/lqos.conf.

Si el shaping de arranque comienza antes de que topology runtime publique la generación actual de shaping_inputs.json, las versiones actuales mantienen el scheduler en un estado de espera de arranque y reintentan el shaping inicial cada pocos segundos. Un mensaje breve como still building outputs for the current source generation justo después de reiniciar normalmente significa que LibreQoS todavía está terminando el ciclo de importación y publicación de runtime, no que el shaping quede detenido hasta la siguiente actualización de 30 minutos.

Si una actualización programada de integración cae mientras topology runtime todavía está publicando salidas para la nueva generación de fuente, las versiones actuales mantienen el scheduler en estado de espera para esa generación y reintentan automáticamente el shaping programado en cuanto topology runtime termina. Trate Scheduled shaping refresh deferred como una espera transitoria solo cuando el mensaje indique que topology runtime todavía está construyendo salidas para la generación actual. Si en cambio indica que topology runtime falló para la generación actual, revise directamente esa falla de runtime.

Si el arranque del scheduler permanece demasiado tiempo en esa espera, o entra en estado degradado con un mensaje indicando que topology runtime falló para la generación actual, revise:

cat /opt/libreqos/state/topology/topology_runtime_status.json
ls -lh /opt/libreqos/state/topology/topology_effective_state.json /opt/libreqos/state/topology/network.effective.json /opt/libreqos/state/shaping/shaping_inputs.json
journalctl -u lqos_scheduler --since "30 minutes ago"
journalctl -u lqosd --since "30 minutes ago"

Si journalctl -u lqosd muestra advertencias repetidas como BeginIngest queue full, IngestChunk queue full o EndIngest queue full durante el arranque o justo después de una importación de topología, los builds anteriores estaban descartando tramas de ingesta hacia Insight porque la cola local del canal de control era demasiado pequeña para ráfagas grandes. Los builds actuales aplican backpressure sobre el socket de Insight para esos lotes de ingesta, por lo que esas advertencias ya no deberían aparecer durante ráfagas cortas de arranque o importación. Si siguen apareciendo después de actualizar, revise primero la presión de CPU de lqosd y la conectividad reciente del canal de control antes de asumir que el shaping está fallando.

RTNETLINK answers: Invalid argument

Suele indicar que no se pudo agregar correctamente qdisc MQ en la NIC (colas RX/TX insuficientes). Verifique NICs recomendadas.

Todas las IPs de clientes aparecen como Unknown IPs

cd /opt/libreqos/src
sudo systemctl stop lqos_scheduler
sudo /opt/libreqos/venv/bin/python /opt/libreqos/src/LibreQoS.py

Corrija errores en ShapedDevices.csv y/o network.json, luego:

sudo systemctl start lqos_scheduler

Flow Globe / Tree Overview / ASN Analysis aparecen en blanco

Algunas vistas requieren suficiente dato reciente para renderizar.

Confirme que lqosd está saludable.
Espere acumulación de tráfico.
Recargue la página tras 1-2 minutos.
Revise logs:

journalctl -u lqosd --since "10 minutes ago"

Si sigue en blanco con tráfico normal, recolecte logs y abra issue.

Los circuitos muestran Generated_PN en vez de nombres de network.json

Si un despliegue DIY/manual usa network.json y ShapedDevices.csv, pero la página de Circuitos muestra padres como Generated_PN_1, revise las entradas de shaping runtime:

jq '.circuits[] | {circuit_id, logical_parent_node_name, effective_parent_node_name, resolution_source}' /opt/libreqos/state/shaping/shaping_inputs.json

Si resolution_source es flat_bucket, LibreQoS está en modo de topología flat. Ese modo asigna intencionalmente los circuitos a colas generadas por CPU en vez de moldearlos bajo la jerarquía nombrada por Parent Node.

Para moldear circuitos bajo los nombres de nodo de network.json, configure:

[topology]
compile_mode = "full"

Después recargue o espere al scheduler para regenerar network.effective.json y shaping_inputs.json.

Colisión de promoción de nodo virtual (`network.json`)

Si LibreQoS.py falla con Virtual node promotion collision: 'AP_A' already exists at this level., hay un nodo con "virtual": true cuyos hijos colisionan por nombre al promoverse.

Renombre nodos en conflicto o reestructure jerarquía para evitar colisiones. Para un visual del flujo lógico-a-físico y la asignación de CPU, consulte Referencia avanzada de configuración.

Se alcanzó el límite de circuitos mapeados

Si ve mensajes como:

Mapped circuit limit reached
Bakery mapped circuit cap enforced

LibreQoS está aplicando un límite de circuitos mapeados.

ShapedDevices.csv puede contener entradas ilimitadas, pero sin un estado válido de licencia/grant de Insight o Local LibreQoS admite solo los primeros 1000 circuitos mapeados válidos al estado de shaping activo.

El límite predeterminado de 1000 circuitos mapeados aplica cuando el estado de licencia/grant está:

ausente
expirado
inválido por cualquier motivo
operando con estado local de grant offline inválido

Síntomas típicos visibles para el operador:

advertencia prominente de límite de circuitos mapeados en WebUI
indicador de uso en la navegación izquierda mostrando cercanía o agotamiento del límite de 1000
mensajes en journalctl -u lqosd con conteos requested/allowed/dropped
shaping parcial, con circuitos fuera del límite activo quedando fuera del estado de shaping

Checks recomendados:

Confirmar el estado de licencia en la página License & Services.
Revisar logs de lqosd para requested/allowed/dropped.
Reducir circuitos mapeados (corto plazo) o ajustar licencia/límites (largo plazo).

Códigos de problemas urgentes y primeras acciones

WebUI muestra códigos legibles por máquina para triage rápido.

Código	Significado	Primeros checks	Ruta de corrección típica
`MAPPED_CIRCUIT_LIMIT`	Bakery está forzando límite de circuitos mapeados.	Estado de licencia Insight y `journalctl -u lqosd` con requested/allowed/dropped.	Reducir circuitos mapeados o actualizar licencia/límites.
`TC_U16_OVERFLOW`	IDs minor de clases/colas excedieron rango u16 de tc en una cola CPU.	`journalctl -u lqos_scheduler -u lqosd`, profundidad topológica y distribución por colas.	Aumentar paralelismo de colas y/o simplificar/rebalancear jerarquía.
`TC_QDISC_CAPACITY`	Los qdisc autoasignados planificados exceden el presupuesto seguro por interfaz o el preflight conservador de seguridad de memoria de Bakery antes de aplicar.	Conteos estimados por interfaz, desglose por tipo de qdisc y campos de memoria en el contexto del urgent issue, `journalctl -u lqos_scheduler -u lqosd`, configuración `on_a_stick` y `monitor_only`.	Reducir la carga planificada de qdisc para esta ejecución (por ejemplo menos circuitos/dispositivos en la forma de prueba) antes de reintentar; no confiar en una aplicación parcial.
`BAKERY_MEMORY_GUARD`	Una recarga completa por fragmentos de Bakery fue detenida a mitad de aplicación porque la memoria disponible del host cayó por debajo del piso de seguridad escalado.	`journalctl -u lqosd`, memoria disponible/total en el contexto del urgent issue y progreso reciente de aplicación de Bakery.	Tratar la ejecución como fallida, reducir presión de memoria o huella de colas y reintentar solo cuando el host esté estable.
`XDP_IP_MAPPING_CAPACITY`	Los mapeos IP requeridos exceden la capacidad actual del mapa XDP en el kernel.	Forma de `ShapedDevices.csv`, mezcla IPv4/IPv6, supuesto de un dispositivo frente a varios dispositivos, `journalctl -u lqos_scheduler -u lqosd`.	Reducir mapeos requeridos de inmediato (por ejemplo menos dispositivos o prueba IPv4-only), o aumentar la capacidad del mapa del kernel en un cambio coordinado.
`XDP_IP_MAPPING_APPLY_FAILED`	Uno o más inserts de mapeo IP fallaron durante la aplicación.	`journalctl -u lqos_scheduler -u lqosd` para ejemplos resumidos y conteos de fallo.	Corregir la causa del fallo y volver a ejecutar; no confiar en shaping parcial.

Patrón operativo:

Abra el detalle del problema urgente en WebUI (código/mensaje/contexto).
Recolecte logs correlacionados de lqosd y lqos_scheduler.
Aplique mitigación inmediata.
Reconozca/limpie el evento en UI cuando esté estable.