본문으로 건너뛰기

문제 해결 (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 참조와 대조할 수 있습니다.