Skip to main content
For the complete documentation index, see llms.txt

Common SDK integration issues

이 문제 해결 가이드는 Midnight.js와 Wallet SDK로 DApp을 개발할 때 자주 마주치는 오류와 그 해결 방법을 안내합니다.

Midnight.js SDK issues​

Midnight.js 오류는 일반적인 JavaScript 클래스입니다. try/catch와 instanceof 연산자로 잡아서 처리하면 됩니다.

트랜잭션이 실행 도중 실패하는 경우​

오류: TxFailedError, DeployTxFailedError, CallTxFailedError, ReplaceMaintenanceAuthorityTxFailedError, RemoveVerifierKeyTxFailedError, InsertVerifierKeyTxFailedError

모든 트랜잭션 오류 클래스는 실패한 트랜잭션의 최종 데이터를 담은 finalizedTxData 속성을 제공합니다. TxFailedError와 CallTxFailedError는 여기에 더해 circuitId 속성도 제공합니다.

확인 사항:

  • 잡은 오류의 finalizedTxData 속성을 확인해 어떤 트랜잭션이 왜 실패했는지 파악하세요.
  • 호출 트랜잭션이라면 circuitId 속성을 확인해 트랜잭션을 구성한 circuit이 무엇인지 파악하세요.
import { CallTxFailedError, DeployTxFailedError } from '@midnight-ntwrk/midnight-js-contracts';

try {
  await client.call(/* ... */);
} catch (error) {
  if (error instanceof CallTxFailedError) {
    console.error('Call failed, tx data:', error.finalizedTxData);
    console.error('Circuit ID:', error.circuitId);
  } else if (error instanceof DeployTxFailedError) {
    console.error('Deploy failed, tx data:', error.finalizedTxData);
  } else {
    throw error;
  }
}

배포된 컨트랙트 타입이 예상과 일치하지 않는 경우​

오류: ContractTypeError

이 오류는 배포된 컨트랙트 상태가 기대한 컨트랙트 타입과 일치하지 않거나, 하나 이상의 검증자 키가 일치하지 않을 때 발생합니다.

확인 사항:

  • circuitIds 속성을 확인해 검증자 키가 정의되지 않았거나 일치하지 않는 circuit이 무엇인지 파악하세요.
  • SDK가 기대하는 검증자 키로 컨트랙트를 컴파일하고 배포했는지 확인하세요.

호출 트랜잭션 설정이 불완전한 경우​

오류: IncompleteCallTxPrivateStateConfig

이 오류는 호출 트랜잭션에서 privateStateProvider를 제공하지 않고 privateStateId만 지정했을 때 발생합니다.

확인 사항:

  • 호출 옵션에 privateStateId를 지정했다면 privateStateProvider도 함께 제공해야 합니다.
  • 오류의 privateStateId와 privateStateProvider 속성을 확인해 SDK가 어떤 값을 받았고 어떤 값이 누락되었는지 살펴보세요.

컨트랙트 조회 설정이 불완전한 경우​

오류: IncompleteFindContractPrivateStateConfig

이 오류는 컨트랙트 조회에서 privateStateId를 제공하지 않고 initialPrivateState만 지정했을 때 발생합니다. 런타임은 다음 메시지를 던집니다.

'initialPrivateState' was defined for contract find while 'privateStateId' was undefined

확인 사항:

  • 조회 옵션에 initialPrivateState를 지정했다면 privateStateId도 함께 지정해야 합니다.
  • 오류의 initialPrivateState와 privateStateId 속성을 확인해 전달된 값을 살펴보세요.

Midnight.js 오류 클래스 전체 목록과 각 속성은 Midnight.js error reference를 참고하세요.

Wallet SDK​

Wallet SDK 오류는 대개 Effect의 Data.TaggedError 인스턴스입니다. 특정 오류를 잡으려면 _tag 값과 함께 Effect.catchTag를 사용하고, 여러 오류를 한꺼번에 처리하려면 Effect.catchTags를 사용하세요.

노드에 연결할 수 없는 경우​

오류: ConnectionError (_tag: 'ConnectionError'), InvalidProtocolSchemeError (_tag: 'InvalidProtocolSchemeError'), FailedToDeriveWebSocketUrlError (_tag: 'FailedToDeriveWebSocketUrlError')

알려진 ConnectionError 메시지:

  • "Could not connect within specified time range (5s)" — 노드에 접근할 수 없거나 응답이 느린 경우입니다.
  • "Failed to retrieve genesis transactions" — 연결은 되었지만 제네시스 데이터를 사용할 수 없는 경우입니다.

확인 사항:

  • 노드 WebSocket URL이 올바른지, 노드가 실행 중인지 확인하세요.
  • 느린 네트워크로 연결한다면 연결 타임아웃을 늘리는 것을 고려하세요.
  • InvalidProtocolSchemeError가 보인다면 모든 네트워크 URL이 예상한 스킴을 사용하는지 확인하세요. WebSocket 연결은 ws:// 또는 wss://, HTTP는 http:// 또는 https://를 사용해야 합니다.

SDK가 노드 응답을 파싱하지 못하는 경우​

오류: ParseError (_tag: 'ParseError')

확인 사항:

  • 이 오류는 대개 SDK와 노드 간의 프로토콜 버전이 일치하지 않음을 나타냅니다.
  • SDK와 노드 버전이 호환되는지 확인하고, 오래된 쪽을 업데이트하세요.
note

작업 중인 환경에 호환되는 SDK와 노드 버전은 항상 Compatibility matrix에서 확인하세요.

노드가 트랜잭션을 유효하지 않다고 거부하는 경우​

오류: TransactionInvalidError (_tag: 'TransactionInvalidError')

확인 사항:

  • 트랜잭션 형식이 잘못되었거나 검증 규칙을 위반해 이 오류가 발생합니다.
  • 트랜잭션 구성 로직을 검토하세요. 수정 없이 다시 제출해서는 안 됩니다.

잔액이 부족한 경우​

오류: InsufficientFundsError (_tag: 'Wallet.InsufficientFunds'), InsufficientFundsError (Capabilities — 일반 Error)

태그드 오류 형태는 tokenType: string과 amount: bigint를 제공합니다. Capabilities 형태는 코인 선택 과정에서 던져지는 일반 JavaScript Error이며, Effect 실패가 아닙니다.

알려진 capabilities 메시지: "Insufficient Funds: could not balance <tokenType>"

확인 사항:

  • 트랜잭션을 구성하기 전에 해당 토큰 타입의 지갑 잔액을 확인하세요.
  • 전송 금액을 줄이거나 충전을 요청하세요.
  • Capabilities의 일반 Error는 Effect.catchTag가 아니라 try/catch나 Effect.tryPromise로 처리하세요.

증명 생성에 실패하는 경우​

오류: ProvingError (_tag: 'Wallet.Proving')

확인 사항:

  • proof server가 실행 중이고 접근 가능한지 확인하세요.
  • 올바른 circuit 키를 로드하고 있는지 확인하세요.
  • 래핑된 cause를 확인해 하위 provider 오류가 무엇인지 파악하세요.

코인에 논스 해시가 없는 경우​

오류: InvalidCoinHashesError (_tag: 'Wallet.InvalidCoinHashes')

확인 사항:

  • 코인을 사용하기 전에 완전히 동기화되었는지 확인하세요.
  • missingNonces 필드를 확인해 영향을 받은 코인을 파악하세요.

주소가 유효하지 않은 경우​

오류: AddressError (_tag: 'Wallet.Address')

AddressError는 거부된 입력값을 담은 originalAddress: string을 제공합니다. 주소 형식 오류는 일반 Error로 던져지며, try/catch로 잡을 수 있습니다.

자주 발생하는 주소 형식 메시지:

  • "Expected prefix mn": 주소가 mn 접두사로 시작하지 않습니다.
  • "Segment contains disallowed characters": 주소 세그먼트에 허용되지 않은 문자가 포함되어 있습니다.
  • "Unshielded address needs to be 32 bytes long": unshielded 주소 페이로드의 길이가 잘못되었습니다.
  • "Dust address is too large": DUST 주소가 허용된 최대 크기를 초과했습니다.

확인 사항:

  • 주소 형식 API에 전달하기 전에 주소 문자열을 검증하세요.
  • 지갑 계층에서의 상위 수준 주소 검증에는 AddressError를 사용하세요.

HTTP 네트워킹 오류​

오류: ClientError (_tag: 'ClientError'), ServerError (_tag: 'ServerError')

확인 사항:

  • ClientError는 HTTP 400~499 상태 코드에 해당합니다. 잘못된 입력, 인증 실패, 리소스를 찾을 수 없음 등 요청 자체에 문제가 있음을 나타냅니다. 요청을 수정하지 않고 재시도하지 마세요. 오류에서 구체적인 상태 코드를 확인하세요.
  • ServerError는 HTTP 500 이상의 상태 코드에 해당합니다. 500 오류가 지속되면 서버 로그를 확인하세요. SDK는 일시적인 502~504 오류에 대해 자동으로 재시도합니다.

Wallet SDK 오류 타입 전체 목록은 Wallet SDK error reference를 참고하세요.