Troubleshooting (FAQ)
Organized as "symptom → cause → fix". Connection failures, auth failures, garbled text and unresolvable variables are the four big categories.
Connection / Send Failures
| Symptom | Likely cause | Fix |
|---|---|---|
| "No base address" reported | Group has no environment bound, or the environment lacks that protocol's Pre-URL | Bind an environment, add the protocol's Pre-URL |
| WS/gRPC/MQTT won't connect | Pre-URL scheme wrong (protocol is classified by scheme) | ws uses ws/wss, grpc uses grpc/grpcs, mqtt uses mqtt/mqtts |
| TCP/UDP won't connect | Host and port swapped | Host takes the address, port is separate |
| TLS errors | Encrypted scheme but no certificate configured | Import a client certificate, or turn off TLS verification as needed |
| Long connection drops suddenly | Reclaimed automatically when idle | Reconnect before use; close old sessions promptly when debugging in batches (quota is capped) |
Auth (401 / 403)
| Symptom | Cause | Fix |
|---|---|---|
| 401 even with a token | The pre-send script didn't run (script execution disabled) | Confirm "execute scripts" is on |
{{authToken}} stays literal (not replaced) | {{}} can't read runtime-stored tokens | Use a pre-send script with sdk.env.get to inject the header (see recipes, scenario 1) |
| Next request can't get the token after login | The two requests are in different groups / environments | Put them in the same group bound to the same environment (runtime variables are scoped per environment) |
Garbled Text / Encoding
| Symptom | Cause | Fix |
|---|---|---|
| Garbled Chinese in the response | Server returns non-UTF-8 (e.g. GBK) | Decode with the matching charset; reproduce via /charset/gbk |
Decryption returns an Error: ... string | Invalid/empty ciphertext, or key/iv differs from encryption ($crypto failures only return an error string, never throw/abort) | Keep encryption/decryption key & iv identical; check whether the return string starts with Error: (Chinese plaintext round-trips fine, verified) |
Script reports Script aborted request | An uncaught JS exception in the script (common: non-ASCII header values in headers.set, or property access on undefined) | Wrap risky calls in try/catch; put UTF-8 content in body/query params and keep header values ASCII |
| Weird base64 result in scripts | Passed a Uint8Array/bytes to $codec/sdk.utils (gets String()-ed into "97,98,99" before encoding) | Always pass strings; both $codec.base64Encode/Decode and sdk.utils.base64Encode/Decode are UTF-8-aware string↔string — pick one |
Scripts Not Taking Effect
| Symptom | Cause | Fix |
|---|---|---|
| Pre-send script changed the body but the wire doesn't show it | No "assignment" rewrite | request.body = new string (assignment replaces the whole body) |
| Post-response rewrite invisible | How to rewrite | response.body = new string; the UI/result view shows the new content after rewriting |
| Script reported as "no entry point, skipped" | Wrong function name | Must be named onRequest / onResponse |
| Scripts can't read each other's values | Unfamiliar with the sharing mechanism | Scripts in the same chain share globalThis — pass values via globalThis.xxx |
| AES "encryption failed" in scripts | Wrong argument shape | $crypto.encryptAES takes positional strings, not an object {text,key,iv} |
Script fails with require: 未找到库 [...] | The library key is wrong, or a user script library was renamed/deleted | Copy the require statement from the library manager (identifier form survives renames); built-in keys are @libs/base64 / @libs/hex; require in comments is ignored and never bundles |
Variable Resolution Cheat Sheet
{{name}}: resolves environment configuration variables / per-send variables only; it cannot read values stored at runtime by scripts.- Reading variables inside scripts: all three layers are readable — use this for cross-request token passing.
- To make extracted values usable by
{{}}too: enable the "write extraction back to environment" setting.
Details: concepts, the variable system.
Still Stuck?
- Get the "minimal working case" running first with
/echo(HTTP) or/ws/echo(WS), then add auth/scripts step by step. - Debug one step at a time: can the request leave at all (can't connect → check Pre-URL/host/port) → do scripts execute (is script execution on) → do variables resolve (which layer)?
- Script-related errors can be cross-checked against the Script API Reference.