For the complete documentation index, see llms.txt
Troubleshoot compiler errors
이 가이드는 Compact 컴파일러에서 자주 발생하는 오류와 그 원인, 해결 방법을 설명합니다.
Exit codes
Compact 컴파일러는 다음 종료 코드를 반환합니다.
| Code | Meaning | Fix |
|---|---|---|
| 0 | 컴파일 성공 | 별도 조치 불필요 |
| 1 | 잘못된 명령줄 인자 | compact compile --help로 올바른 플래그를 확인하세요 |
| 255 | 컴파일 실패 | 보고된 소스 오류를 수정한 뒤 다시 컴파일하세요 |
Error severity levels
Compact 컴파일러는 다음 오류 심각도 수준을 사용합니다.
| Mechanism | Severity | Description |
|---|---|---|
source-errorf | Fatal | 소스 위치가 포함된 사용자 노출 오류 |
source-warningf | Warning | 소스 위치가 포함된, 진행 가능한 경고 |
pending-errorf | Deferred | 모아 두었다가 해당 패스 이후 함께 표시되는 오류 |
internal-errorf | Fatal | 컴파일러 내부 버그. Compact 팀에 보고하세요 |
external-errorf | Fatal | 외부 도구 또는 파일 시스템 오류 |
Lexer errors
토큰화 과정에서, 파싱이 시작되기 전에 발생하는 오류입니다.
Unexpected end of file
Message: "unexpected end of file"
Triggers: 닫히지 않은 문자열 리터럴이나 block comment 안에서 파일 끝에 도달한 경우입니다.
Fix: 소스 파일에서 닫히지 않은 문자열("…)과 닫히지 않은 block comment(/* …)가 없는지 확인하세요.
Unexpected newline
Message: "unexpected newline"
Triggers: 단일 행 문자열 리터럴 안처럼 줄바꿈이 허용되지 않는 위치에서 줄바꿈을 만난 경우입니다.
Fix: 문자열 리터럴이 여러 줄에 걸치지 않도록 하세요. 대신 문자열 연결이나 지원되는 여러 줄 구문을 사용하세요.
Unexpected character
Message: "unexpected character '<c>'"
Triggers: Compact 소스 코드에서 허용되지 않는 문자를 만난 경우입니다.
Fix: 잘못된 문자를 제거하거나 다른 문자로 바꾸세요. 외부에서 복사한 비 ASCII 문자, 잘못 들어간 문장 부호, 보이지 않는 유니코드 문자가 없는지 확인하세요.
Nested block comment
Message: "attempt to nest block comment"
Triggers: 이미 열려 있는 /* */ block comment 안에서 /*를 다시 사용한 경우입니다.
Fix: Compact는 중첩된 block comment를 지원하지 않습니다. 내부 주석에는 line comment(//)를 사용하거나, 중첩이 생기지 않도록 구조를 바꾸세요.
Numeric literal out of Field range
Message: "<value> is out of Field range"
Triggers: 숫자 리터럴이 표현 가능한 최대 Field 값을 초과한 경우입니다.
Fix: 더 작은 숫자를 사용하세요. Field 값은 ZK 증명 시스템에 사용되는 소수로 그 범위가 제한됩니다.
Invalid digit in binary literal
Message: "unexpected digit <d> (expected 0 or 1)"
Triggers: 0b… 리터럴에 0 또는 1이 아닌 숫자가 들어간 경우입니다.
Fix: 이진 리터럴에는 숫자 0과 1만 사용할 수 있습니다.
Invalid digit in octal literal
Message: "unexpected digit <d> (expected 0 through 7)"
Triggers: 0o… 리터럴에 숫자 8 또는 9가 들어간 경우입니다.
Fix: 8진수 리터럴에는 0부터 7까지의 숫자만 사용할 수 있습니다.
Parser errors
토큰화 이후 컴파일러가 AST를 구성하는 동안 발생하는 오류입니다.
Parse error
Message: "parse error: found <token> looking for <expected>"
Triggers: 현재 파싱 위치에서 Compact 문법과 일치하지 않는 모든 구문에서 발생합니다.
Fix: 오류 위치를 꼼꼼히 확인하세요. 흔한 원인은 다음과 같습니다.
- 문장 끝의 세미콜론 누락
- 짝이 맞지 않는 중괄호
{/} - 잘못되거나 철자가 틀린 키워드
- 인자 목록에 콤마가 더 있거나 빠진 경우
Unrecognized pragma setting
Message: "unrecognized pragma setting <value>"
Triggers: pragma 지시문에 컴파일러가 인식하지 못하는 값을 사용한 경우입니다.
Fix: 지원되는 pragma 지시문을 확인하세요. 올바른 pragma 예시는 다음과 같습니다.
pragma language_version >= 0.23;
File I/O errors
컴파일러는 다음 메시지를 반환합니다.
"error opening source file""error reading source file""<path> is a directory"
Triggers: 지정한 소스 파일을 열거나 읽는 과정에서 오류가 발생했거나, 경로가 디렉터리를 가리키는 경우입니다.
Fix: 파일 경로가 올바른지, 파일이 존재하는지, 확장자가 .compact인지 확인하세요. 컴파일러가 파일을 기대하는 자리에 디렉터리 경로를 전달하지 마세요.
Witness and disclosure errors
witness 값에 대한 Compact의 프라이버시 모델을 강제하는 오류입니다.
Undeclared witness disclosure
Message: "potential witness-value disclosure must be declared but is not"
Triggers: witness 값이 disclose() 래퍼 없이 ledger나 공개 출력으로 전달된 경우입니다.
Fix: witness 값이 ledger 상태나 공개 출력에 도달하기 전에 disclose()로 감싸세요.
disclose(witnessValue)
disclose() 래퍼는 비공개 데이터를 공개 ledger 상태에 기록해도 안전하다고 선언합니다.
Witness returns contract-typed value
Message: "invalid type <T> for witness <W> return value: witness return values cannot include contract values"
Triggers: witness 함수가 컨트랙트 타입 값을 포함하는 반환 타입을 선언한 경우입니다.
Fix: witness 반환 타입에서 컨트랙트 타입 값을 모두 제거하세요. witness는 struct, enum 등 일반 타입은 반환할 수 있지만 컨트랙트 값은 반환할 수 없습니다. 컨트랙트 관련 정보는 개별 필드로 나눠 전달하세요.
ZKIR generation errors
타입 검사를 마친 AST에서 컴파일러가 ZK 중간 표현(ZKIR)을 생성할 때 발생하는 오류입니다.
Cross-contract calls not supported by this toolchain
Message: "cross-contract calls are not yet supported"
Triggers: 컨트랙트가 ledger 버전 9 이전을 대상으로 컴파일하거나 ZKIR v2 출력으로 컴파일하면서 cross-contract 호출을 하는 경우입니다. cross-contract 호출은 ledger 버전 9과 ZKIR v3(toolchain 0.33.0 이상)에서 도입되었습니다.
Fix: 대상 네트워크가 운영하는 ledger 버전을 compatibility matrix에서 확인하세요. 9 이전이면 cross-contract 호출을 쓰지 않도록 컨트랙트 구조를 바꾸세요. 9 이상이면 이를 지원하는 toolchain을 사용하고 --feature-zkir-v3로 컴파일하세요. 언어 레퍼런스의 Cross-contract calls와 Compact release notes를 참고하세요.
ZKIR non-zero exit status
Message: "zkir returned a non-zero exit status <N>"
Triggers: 외부 ZKIR 컴파일 도구가 오류로 종료된 경우입니다.
Fix: 지원되지 않는 연산에 대한 자세한 내용은 출력을 확인하세요. circuit 안에 ZKIR 백엔드가 아직 지원하지 않는 연산이 없는지 점검하세요.
Runtime errors
컴파일러가 아니라, 컴파일된 컨트랙트가 Midnight 런타임에서 실행될 때 발생하는 오류입니다.
Base error class
Class: CompactError
Description: CompactError는 모든 컨트랙트 런타임 오류의 기반 클래스입니다. 이 타입을 catch하면 어떤 Compact contract 오류든 일괄적으로 처리할 수 있습니다.
Failed assertion
Message: "failed assert: <message>"
Triggers: Compact assert 식이 런타임에 false로 평가된 경우입니다.
Fix: assertion 조건을 점검하세요. <message> 텍스트는 assert에 전달한 문자열입니다. 이를 단서로 컨트랙트 소스에서 해당 assertion을 찾아 조건이 충족되지 않은 이유를 확인하세요.
Runtime type error
Message: "type error: <who> <what> at <where>; expected value of type <type> but received <value>"
Triggers: 생성된 코드에서 런타임 타입 불일치가 발생한 경우로, 보통 선언된 witness 반환 타입과 런타임에 실제로 생성된 값이 어긋날 때 나타납니다.
Fix: witness 반환 타입을 확인하세요. TypeScript witness 구현이 Compact contract에 선언된 타입에 맞는 값을 반환하는지 점검하세요.
Version mismatch
Message: "version mismatch: compiled code expects X.Y.Z, runtime is A.B.C"
Triggers: 스마트 컨트랙트를 컴파일한 Compact 컴파일러 버전과, 실행에 사용한 @midnight-ntwrk/compact-runtime 버전이 다른 경우입니다.
Fix: 프로젝트의 @midnight-ntwrk/compact-runtime을 컨트랙트 빌드에 사용한 컴파일러 버전에 맞게 업데이트하세요. 또는 런타임 버전에 맞는 컴파일러로 컨트랙트를 다시 컴파일하세요.
호환성 매트릭스를 참조하여 어떤 버전끼리 호환되는지 항상 확인하세요.