Resolución de problemas (FAQ)
Organizado como «síntoma → causa → solución». Fallos de conexión, fallos de autenticación, texto ilegible y variables sin resolver son las cuatro grandes categorías.
Fallos de conexión / envío
| Síntoma | Causa probable | Solución |
|---|---|---|
| Se informa «sin dirección base» | El grupo no tiene entorno vinculado, o al entorno le falta la Pre-URL de ese protocolo | Vincula un entorno, añade la Pre-URL del protocolo |
| WS/gRPC/MQTT no conecta | Scheme de Pre-URL incorrecto (el protocolo se clasifica por el scheme) | ws usa ws/wss, grpc usa grpc/grpcs, mqtt usa mqtt/mqtts |
| TCP/UDP no conecta | Host y puerto intercambiados | El host lleva la dirección, el puerto va aparte |
| Errores TLS | Scheme cifrado pero sin certificado configurado | Importa un certificado de cliente, o desactiva la verificación TLS si lo necesitas |
| La conexión larga se corta de repente | Se recupera automáticamente cuando está inactiva | Reconecta antes de usar; cierra las sesiones antiguas al depurar en serie (el cupo es limitado) |
Autenticación (401 / 403)
| Síntoma | Causa | Solución |
|---|---|---|
| 401 incluso con token | El script de envío previo no se ejecutó (ejecución de scripts desactivada) | Confirma que «ejecutar scripts» está activado |
{{authToken}} queda literal (sin reemplazar) | {{}} no puede leer tokens guardados en ejecución | Usa un script de envío previo con sdk.env.get para inyectar la cabecera (ver recetas, escenario 1) |
| La siguiente solicitud no obtiene el token tras el login | Las dos solicitudes están en grupos / entornos distintos | Ponlas en el mismo grupo vinculado al mismo entorno (las variables de ejecución se acotan por entorno) |
Texto ilegible / codificación
| Síntoma | Causa | Solución |
|---|---|---|
| Chino ilegible en la respuesta | El servidor devuelve no-UTF-8 (p. ej. GBK) | Decodifica con el charset correspondiente; reproduce con /charset/gbk |
El descifrado devuelve una cadena Error: ... | Cifrado inválido/vacío, o key/iv distinto del cifrado ($crypto solo devuelve cadenas de error, nunca lanza/aborta) | Mantén key e iv idénticos al cifrar y descifrar; comprueba si la cadena devuelta empieza por Error: (el texto claro chino va y vuelve bien, verificado) |
El script informa Script aborted request | Una excepción JS no capturada en el script (habitual: valores de cabecera no ASCII en headers.set, o acceso a propiedades de undefined) | Envuelve las llamadas arriesgadas en try/catch; pon contenido UTF-8 en el body/params de query y mantén los valores de cabecera en ASCII |
| Resultado base64 extraño en scripts | Se pasó un Uint8Array/bytes a $codec/sdk.utils (se convierte con String() a "97,98,99" antes de codificar) | Pasa siempre cadenas; tanto $codec.base64Encode/Decode como sdk.utils.base64Encode/Decode son UTF-8-safe string↔string — elige uno |
Los scripts no surten efecto
| Síntoma | Causa | Solución |
|---|---|---|
| El script de envío previo cambió el body pero en la línea no aparece | No hay reescritura por «asignación» | request.body = new string (la asignación reemplaza todo el body) |
| La reescritura post-respuesta no se ve | Cómo reescribir | response.body = new string; la vista de UI/resultado muestra el nuevo contenido tras reescribir |
| El script se informa como «sin punto de entrada, omitido» | Nombre de función incorrecto | Debe llamarse exactamente onRequest / onResponse |
| Los scripts no se leen valores entre sí | Mecanismo de compartición desconocido | Los scripts de la misma cadena comparten globalThis — pasa valores mediante globalThis.xxx |
| AES «falló el cifrado» en scripts | Forma de argumentos incorrecta | $crypto.encryptAES toma cadenas posicionales, no un objeto {text,key,iv} |
El script falla con require: 未找到库 [...] | La clave de biblioteca es incorrecta, o se renombró/borró una biblioteca de scripts de usuario | Copia la sentencia require desde el gestor de bibliotecas (la forma por identificador sobrevive a los renombrados); las claves integradas son @libs/base64 / @libs/hex; los require en comentarios se ignoran y nunca se empaquetan |
Chuleta de resolución de variables
{{name}}: resuelve solo variables de configuración del entorno / de envío; no puede leer valores guardados en tiempo de ejecución por los scripts.- Leer variables dentro de scripts: las tres capas son legibles — úsalo para pasar tokens entre solicitudes.
- Para que los valores extraídos también sirvan a
{{}}: activa el ajuste «escribir la extracción de vuelta al entorno».
Detalles: conceptos clave, el sistema de variables.
¿Sigues atascado?
- Consigue primero el «caso mínimo funcional» con
/echo(HTTP) o/ws/echo(WS) y añade auth/scripts paso a paso. - Depura de uno en uno: ¿la solicitud sale del dispositivo? (no conecta → revisa Pre-URL/host/puerto) → ¿se ejecutan los scripts? (¿está activada la ejecución de scripts?) → ¿se resuelven las variables? (¿qué capa?)
- Los errores de scripts se pueden contrastar con la Referencia de la API de scripts.