Objetivo del tema
Aprender a diagnosticar fallos frecuentes en Qwen Code, distinguir problemas de instalación, autenticación, permisos, sandbox, MCP, IDE o configuración, y adoptar un conjunto de buenas prácticas que reduzcan errores antes de que aparezcan.
Este tema se apoya en la documentación oficial disponible al 11 de abril de 2026, especialmente en Troubleshooting guide, settings.json, Sandbox, Qwen Ignore y las guías de integración con IDE.
Uno de los errores más comunes al trabajar con herramientas complejas es intentar resolver todo con intuición. En Qwen Code eso suele llevar a perder tiempo, porque el síntoma visible rara vez indica por sí solo la causa real.
Por ejemplo, una respuesta como “no funciona” puede esconder problemas muy distintos:
PATHDiagnosticar bien significa separar esas capas y confirmar cada una con evidencia, en lugar de cambiar configuraciones al azar.
La forma más rápida de resolver problemas en Qwen Code no es “probar cualquier cosa”, sino acotar el fallo hasta convertirlo en un caso pequeño y verificable.
Ante cualquier problema, conviene recorrer siempre esta secuencia mínima:
En términos concretos, los primeros comandos razonables suelen ser estos:
qwen --version
qwen auth status
qwen
Si alguno de esos tres pasos ya falla, no tiene sentido avanzar a problemas más sofisticados.
La guía oficial lo describe de manera directa: si al ejecutar qwen el sistema dice que el comando no existe, el problema suele ser uno de estos:
npm no está en PATHLa solución base indicada por la documentación es:
npm install -g @qwen-code/qwen-code@latest
Si el problema sigue, el siguiente paso razonable es verificar dónde instala npm sus binarios globales y si esa carpeta forma parte del PATH efectivo del sistema.
Cuando el CLI arranca pero no puede autenticarse, conviene distinguir entre tres causas grandes:
Comandos base para revisar esto:
qwen auth
qwen auth status
Si usás API keys, además hay que revisar que la variable de entorno o el archivo .env se cargue en el lugar correcto y no en una ubicación que Qwen Code ignore por diseño.
La guía oficial menciona explícitamente errores como:
UNABLE_TO_GET_ISSUER_CERT_LOCALLY
unable to get local issuer certificate
La causa habitual es una red corporativa con inspección TLS/SSL. En esos casos, Node.js no confía automáticamente en el certificado raíz de la empresa.
La solución documentada consiste en apuntar NODE_EXTRA_CA_CERTS al certificado raíz corporativo:
NODE_EXTRA_CA_CERTS=/ruta/al/certificado-root-ca.crt
Este es un caso típico donde el problema no es Qwen Code en sí, sino el entorno de red en el que se ejecuta.
La documentación de troubleshooting marca un caso muy concreto: si existen variables como CI, CONTINUOUS_INTEGRATION o cualquier variable que empiece con CI_, Qwen Code puede interpretar que está corriendo en un entorno no interactivo.
El efecto visible es claro: no aparece el prompt interactivo esperado.
La causa viene de cómo ciertas dependencias detectan entornos CI. Por eso, si estás trabajando localmente pero heredaste variables de un sistema de integración, conviene limpiar ese contexto antes de culpar al CLI.
.env del proyectoOtro detalle que la documentación resalta es que variables como DEBUG y DEBUG_MODE se excluyen automáticamente del .env del proyecto para evitar interferencias accidentales con el comportamiento del CLI.
Eso significa que esta estrategia puede no funcionar:
# .env del proyecto
DEBUG=true
La recomendación actual es usar un archivo .qwen/.env o ajustar la configuración para excluir menos variables del contexto del proyecto.
Muchas veces el usuario cree que “Qwen Code no puede editar”, cuando en realidad el sistema está funcionando exactamente como fue configurado. Si la sesión corre en plan o en un modo más restrictivo, las herramientas de escritura o ejecución pueden quedar bloqueadas.
En ese caso, hay que revisar:
Antes de relajar permisos, conviene preguntarse si el problema es realmente una limitación injustificada o si la política actual está evitando una acción riesgosa.
La guía oficial menciona mensajes del estilo:
Operation not permitted
Permission denied
Cuando el sandbox está activo, estos errores suelen indicar que Qwen Code intentó escribir fuera del directorio permitido, acceder a una ruta no habilitada o ejecutar algo restringido por el proveedor de sandbox.
La forma correcta de diagnosticar esto no es desactivar el sandbox inmediatamente, sino revisar:
EADDRINUSELa documentación incluye un caso clásico:
EADDRINUSE
Esto significa que el puerto ya está siendo usado por otro proceso. No es un fallo misterioso del protocolo MCP: simplemente hay una colisión de puertos.
Las dos salidas razonables son:
Cuando un servidor MCP aparece configurado pero no ofrece herramientas utilizables, conviene revisar varios frentes:
includeTools y excludeTools están filtrando más de lo esperadoEn general, el mejor diagnóstico consiste en aislar el problema: primero verificar que el servidor vivo funcione por sí mismo, y recién después probar la integración con Qwen Code.
La guía oficial dedica una sección específica al companion de IDE. En VS Code, los fallos más habituales son:
host.docker.internal no resuelve bienLas variables que la documentación menciona como críticas son:
QWEN_CODE_IDE_WORKSPACE_PATH
QWEN_CODE_IDE_SERVER_PORT
La solución más sensata suele ser reiniciar el terminal integrado, reinstalar con /ide install y ejecutar Qwen Code: Run desde la paleta de comandos.
.qwenignoreLa documentación de .qwenignore muestra otra fuente frecuente de confusión. Si un archivo está listado allí, ciertas herramientas dejarán de considerarlo. Eso puede generar la sensación de que “Qwen Code no ve el archivo”, cuando en realidad la exclusión fue configurada a propósito.
Por eso conviene tratar .qwenignore como una herramienta de precisión, no como un volcado masivo de carpetas. Un archivo importante ignorado por error puede alterar bastante el contexto que recibe el agente.
Una buena parte de los problemas operativos no viene del modelo ni del CLI, sino de rutas equivocadas. Estos son errores muy comunes:
qwen en una carpeta distinta del proyecto realsettings.json fuera de .qwen/cwd mal resueltoPor eso, cada vez que algo “parece ignorado”, conviene validar primero la ruta antes de suponer un bug más profundo.
La guía oficial recomienda aumentar el nivel de diagnóstico cuando un problema no es evidente. Entre las medidas sugeridas están:
--verbose si está disponibleEl principio importante es este: si un fallo se repite, tiene que dejar evidencia en algún punto. El trabajo del diagnóstico consiste en encontrar ese rastro.
La documentación para desarrolladores aconseja ejecutar comprobaciones previas antes de dar por hecho que el error está en el modelo o en el CLI. En proyectos Node, una recomendación explícita es:
npm run preflight
Eso ayuda a detectar problemas de lint, formato, tipos o build que de otro modo podrían confundirse con un fallo del agente.
Cuando el problema no es obvio, conviene reducir el escenario hasta dejarlo en su forma más pequeña posible. Un orden razonable sería:
Este método evita que varios factores se mezclen y permite descubrir cuál es la capa que realmente está fallando.
Más allá del troubleshooting puntual, hay hábitos que reducen mucho la tasa de errores:
.qwen/settings.json cuando tenga sentido para el equipoEstas prácticas parecen simples, pero evitan una parte muy grande de los problemas que después se viven como “errores del sistema”.
| Síntoma | Primera sospecha | Primer paso |
|---|---|---|
No existe el comando qwen |
Instalación o PATH | Revisar instalación global y binarios |
| No aparece prompt interactivo | Variables de CI | Inspeccionar entorno heredado |
| No puede escribir archivos | Approval mode o sandbox | Revisar permisos y rutas |
| MCP falla al arrancar | Puerto ocupado o config incorrecta | Revisar logs y puerto |
| IDE no conecta | Workspace múltiple o terminal sin variables | Reiniciar terminal y verificar workspace |
| La configuración parece ignorada | Archivo mal ubicado o prioridad distinta | Revisar ruta y precedencia |
La documentación recomienda buscar primero issues existentes en GitHub y, si no encontrás uno equivalente, crear un informe nuevo con detalles suficientes.
Un buen reporte debería incluir como mínimo:
Sin esa información, incluso un problema real puede quedar difícil de reproducir y por lo tanto difícil de resolver.
Trabajar bien con Qwen Code no consiste solo en conocer sus comandos. También exige entender dónde puede fallar, cómo aislar un problema y qué señales conviene observar antes de tocar la configuración.
En este tema vimos las ideas esenciales:
.qwenignore, settings.json y el directorio actual influyen mucho más de lo que parece.Con esta base, el curso ya está listo para cerrar con casos de uso completos y estrategia de adopción, donde todas estas piezas se combinan en escenarios reales de trabajo.