문제 해결 (FAQ)
'증상 → 원인 → 해결' 순으로 정리했습니다. 연결 실패, 인증 실패, 문자 깨짐, 변수 미해석이 4대 카테고리입니다.
연결 / 전송 실패
| 증상 | 가능한 원인 | 해결 |
|---|---|---|
| '베이스 주소가 없다'고 표시됨 | 그룹에 환경이 바인딩되지 않았거나, 환경에 그 프로토콜의 Pre-URL이 없음 | 환경을 바인딩하고, 해당 프로토콜의 Pre-URL을 추가 |
| WS/gRPC/MQTT가 연결되지 않음 | Pre-URL의 scheme이 틀림(프로토콜은 scheme으로 분류됨) | ws는 ws/wss, grpc는 grpc/grpcs, mqtt는 mqtt/mqtts 사용 |
| TCP/UDP가 연결되지 않음 | host와 port를 서로 바꿔 입력함 | host가 주소, port는 별도 필드 |
| TLS 오류 | 암호화 scheme인데 인증서가 미설정 | 필요에 따라 클라이언트 인증서 임포트 또는 TLS 검증 끄기 |
| 장기 접속이 갑자기 끊김 | 아이들 시 자동 회수됨 | 사용 전에 재접속; 연속 디버깅 시 오래된 세션을 즉시 닫기(쿼터에 상한 있음) |
인증 (401 / 403)
| 증상 | 원인 | 해결 |
|---|---|---|
| 토큰이 있는데도 401 | 전송 전 스크립트가 실행되지 않음(스크립트 실행이 꺼짐) | '스크립트 실행'이 켜져 있는지 확인 |
{{authToken}}이 그대로 남음(치환되지 않음) | {{}}는 런타임에 저장된 토큰을 읽을 수 없음 | sdk.env.get을 쓰는 전송 전 스크립트로 헤더에 주입(recipes, 시나리오 1 참조) |
| 로그인 후 다음 요청에서 토큰을 못 얻음 | 두 요청이 다른 그룹 / 다른 환경에 있음 | 같은 환경에 바인딩된 같은 그룹에 배치(런타임 변수는 환경 단위 스코프) |
문자 깨짐 / 인코딩
| 증상 | 원인 | 해결 |
|---|---|---|
| 응답의 중국어가 깨짐 | 서버가 비UTF-8(예: GBK)을 돌려줌 | 대응하는 charset으로 디코딩; /charset/gbk로 재현 |
복호화가 Error: ... 문자열을 돌려줌 | ciphertext가 무효/비어 있음, 또는 키/iv가 암호화 때와 다름($crypto 실패는 오류 문자열만 돌려주고 예외·중단하지 않음) | 암호화/복호화에서 키와 iv를 동일하게; 반환값이 Error:로 시작하는지 확인(중국어 평문 왕복은 문제 없음, 검증됨) |
스크립트가 Script aborted request를 보고 | 스크립트 내 미포착 JS 예외(흔한 원인: headers.set의 비ASCII 헤더 값, undefined 프로퍼티 접근) | 위험한 호출은 try/catch로 감싸기; UTF-8 내용은 body/쿼리 파라미터로, 헤더 값은 ASCII로 유지 |
| 스크립트의 base64 결과가 이상함 | Uint8Array/bytes를 $codec/sdk.utils에 전달함(인코딩 전 String()화로 "97,98,99"가 됨) | 항상 문자열을 전달; $codec.base64Encode/Decode와 sdk.utils.base64Encode/Decode는 모두 UTF-8 대응 string↔string — 하나로 통일 |
스크립트가 적용되지 않음
| 증상 | 원인 | 해결 |
|---|---|---|
| 전송 전 스크립트로 바디를 바꿨는데 와이어에 반영되지 않음 | '대입'에 의한 재작성이 아님 | request.body = new string(대입이 바디 전체를 교체) |
| 응답 후 재작성이 보이지 않음 | 재작성 방법 | response.body = new string; UI/결과 뷰에 재작성 후 내용이 표시됨 |
| 스크립트가 '엔트리 포인트 없음, 건너뜀'으로 보고됨 | 함수 이름이 다름 | 반드시 onRequest / onResponse라는 이름이어야 함 |
| 스크립트끼리 서로의 값을 읽지 못함 | 공유 메커니즘에 대한 이해 부족 | 같은 체인의 스크립트는 globalThis를 공유합니다 — globalThis.xxx로 값을 전달 |
| 스크립트에서 AES '암호화 실패' | 인자 형태가 다름 | $crypto.encryptAES는 위치 지정 문자열을 받고, {text,key,iv} 객체가 아님 |
스크립트가 require: 未找到库 [...]로 실패 | 라이브러리 키가 틀렸거나, 사용자 스크립트 라이브러리가 리네임/삭제됨 | 라이브러리 매니저에서 require 문을 복사(identifier 형태는 리네임에 강함); 내장 키는 @libs/base64 / @libs/hex; 주석 안의 require는 무시되며 번들도 되지 않음 |
변수 해석 치트시트
{{name}}: 해석 하는 것은 환경 설정 변수 / 전송 시 변수뿐입니다. 스크립트가 런타임에 저장한 값은 읽을 수 없습니다.- 스크립트 내 변수 읽기: 3계층 모두 읽을 수 있습니다 — 요청 간 토큰 전달에 사용합니다.
- 추출한 값을
{{}}에서도 쓰게 하려면: '추출 결과를 환경에 쓰기' 설정을 켭니다.
자세히: concepts, 변수 시스템.
그래도 해결되지 않으면
- 먼저
/echo(HTTP)나/ws/echo(WS)로 '최소 동작 케이스'를 돌리고, 거기에 인증 / 스크립트를 한 단계씩 추가합니다. - 한 단계씩 분리: 요청이 나가고 있는가(연결 안 됨 → Pre-URL/host/port 확인) → 스크립트가 실행되고 있는가(스크립트 실행 켜짐?) → 변수가 해석되고 있는가(어느 레이어?)?
- 스크립트 관련 오류는 스크립트 API 참조와 대조할 수 있습니다.