본문으로 건너뛰기

자주 발생하는 오류 해결하기

이 페이지는 일반적인 error에 대한 troubleshooting 해결책을 제공한다.

Address 오류​

이 섹션의 error는 Sui address와 관련이 있다.

Failed to build Move modules: Unresolved addresses found.​

이 error는 std 같은 named address를 코드나 dependency 안에서 사용하려고 하지만 Move.toml file에서 그 address에 값을 할당하지 않았음을 나타낸다.

해결 방법​

해결되지 않은 각 address에 대한 entry를 Move.toml file의 [addresses] section에 추가한다.

[addresses]
std = "0x1"

리소스

Invalid Sui Address​

이 error는 제공한 address가 유효한 Sui address format을 따르지 않음을 나타낸다. Sui address는 다음 조건을 충족해야 한다:

  • 32-byte hex-encoded string이어야 한다.

  • 0x로 시작하고 hexadecimal 문자(0-9, a-f, A-F)만 포함해야 한다.

해결 방법​

제공하는 address가 0x로 시작하고, 64개의 hex digit 길이를 가지며, 유효하지 않은 문자를 포함하지 않는지 확인한다.

리소스

Move package 오류​

이 섹션의 error는 Move package와 관련이 있다.

Invalid URL: Invalid URL: relative URL without a base​

이 error는 system이 URL string을 relative URL(/path/to/file)로 해석하지만 코드가 absolute URL(https://example.com/path/to/file)을 기대할 때 발생한다. 이 error는 URL과 상호작용하기 위한 Url struct와 function을 제공하는 sui::url module에서 발생한다. Move는 URL 자체의 format을 검증하지 않는다.

해결 방법​

http:// 또는 https://를 포함한 전체 URL path를 지정한다.

리소스

Failed to build Move modules: Failed to resolve dependencies for package​

이 error는 system이 Move package의 Move.toml file에 나열한 dependency 중 하나 이상을 찾을 수 없음을 나타낸다. system이 dependency를 찾을 수 없는 경우는 다음과 같다:

  • path가 잘못되었거나 typo가 있거나 존재하지 않는다.

  • manifest file이 존재하지 않는다.

  • 제대로 initialize하지 않았다.

해결 방법​

Move.toml을 확인하여 나열한 각 dependency가 올바른 path를 가지는지, 그리고 각 path 안에 유효한 Move.toml file이 있는지 검증한다. typo가 없는지 확인하고 모든 dependency를 initialize했는지 확인한다.

리소스

Duplicate module found: 0x0000000000000000000000000000000000000000000000000000000000000002::groth16​

이 error는 프로젝트 또는 그 dependency에 같은 이름이나 address를 가진 module이 둘 이상 정의되어 있음을 나타낸다. 각 module에는 고유한 이름과 address 조합을 부여해야 한다.

해결 방법​

source file에서 같은 module 이름이나 address를 두 번 사용하지 않는지 확인한다. package의 dependency에 duplicate name이 정의되어 있는지 확인한다. Move.toml file에 충돌하는 address assignment가 있는지 확인한다.

리소스

Internal error occurred while processing request: Error resolving Move location: Linkage not found for package​

이 error는 environment 또는 tooling이 지정된 address에서 Move package를 찾을 수 없음을 나타낸다. 가능한 원인은 다음과 같다:

  • package를 network에 publish하지 않았다.

  • address가 잘못되었다.

해결 방법​

지정된 address에 package가 network에 존재하는지 확인한다.

Failed to build Move modules: Compilation error.​

이 error는 Move code 어딘가가 compiler의 규칙을 위반하여 compiler가 package를 bytecode로 compile할 수 없음을 나타내는 generic error이다.

해결 방법​

이 error의 일반적인 원인으로는 다음이 있다:

  • Unbound variable or module: package에서 참조하는 모든 module과 variable을 선언했고 scope 안에 있는지 확인한다.

  • Duplicate declaration, item, or annotation: function, struct, module 이름이 namespace 안에서 모두 고유한지 확인한다.

  • Invalid declaration: module을 올바르게 선언하려면 항상 module에 address를 지정한다.

  • Unbound type or member: 모든 type과 member를 올바르게 정의하고 import해야 한다.

  • Edition not specified: 모든 Move.toml file에 edition = "2024" field를 정의해야 한다.

리소스

Failed to publish the Move module(s), reason: Modules must all have 0x0 as their addresses.​

이 error는 package 안의 module이 0x0 address를 가지지 않음을 나타낸다. Move에서는 source code에서 모든 module의 self-address를 0x0으로 설정해야 한다. package를 publish할 때 Sui가 올바른 address를 자동으로 할당한다.

해결 방법​

Move source file에서 명시적인 address block을 제거한다. module을 address ... { ... } block으로 감싸지 않는다.

리소스

The signer only expects one signature, not two​

이 error는 Move module에서 호출하는 function이 signer argument 1개를 기대하는데 2개를 제공했음을 나타낸다. Sui에서는 function signature의 signer argument 수가 제공하는 signer 수와 일치해야 한다.

해결 방법​

function을 fun main(s: signer)로 정의했다면 signer도 1개만 제공해야 하는지 확인한다.

signer 2개를 사용하려면 fun main(s1: signer, s2: signer) { ... }로 function을 정의한다.

리소스

destroy_zero​

이 error는 0이 아닌 값을 가진 resource를 destroy하려고 함을 나타낸다.

해결 방법​

resource의 값이 0인지 확인한다. coin이나 token의 경우 값이 0이 될 때까지 split하거나 burn한다.

리소스

System 오류​

이 섹션의 error는 system과 관련이 있다.

"Segmentation fault (core dumped)"​

이 error는 low-level memory crash를 나타낸다. 이는 Move error가 아니라 Move compiler 또는 dependency 같은 toolchain 일부의 error이다.

해결 방법​

일부 상황에서는 오래되었거나 손상된 build file이 이 crash의 원인이 될 수 있다. build를 정리한다:

$ sui move clean

다른 시나리오에서는 오래되었거나 맞지 않는 tooling version이 이 error의 원인이 될 수 있다. tooling을 업그레이드하고 version이 일치하는지 확인한다.

리소스

Failed to build Move modules: Permission denied (os error 13).​

이 error는 permission이 충분하지 않아 Move가 file 또는 directory에 접근할 수 없음을 의미한다.

해결 방법​

대상 file 또는 directory에 대해 사용자 계정에 필요한 read, write, execute permission이 있는지 확인한다.

Unix와 macOS system에서는 chmod command로 permission을 편집할 수 있다:

$ chmod -R u+rw /path/to/project/files

이 명령은 지정한 file path의 모든 file과 subdirectory에 read와 write permission을 부여한다.

리소스

sui move build command hang 문제​

이 동작은 Windows 11 machine에서 command를 실행할 때 자주 발생한다.

해결 방법​

Windows-native terminal에서 command를 실행하는 대신 Windows machine에서 Windows Subsystem for Linux를 사용해 본다.

리소스

Fetch failed error (cause: Header Timeout)​

이 error는 network가 일정 시간 안에 response를 받지 못함을 나타낸다. 이 error는 Sui에만 특화된 것은 아니다.

해결 방법​

request를 다시 시도하거나 client를 제어할 수 있다면 timeout 시간을 늘린다.

Transaction 오류​

이 섹션의 error는 transaction과 관련이 있다.

Requires a connection to the network. Current active network is [testnet/mainnet/devnet] but failed to connect to it.​

이 error는 network가 다운되었거나, 불안정한 인터넷 연결 때문에 도달할 수 없거나, Sui client configuration에 잘못된 설정이 있을 때 발생한다.

해결 방법​

먼저 client에 구성된 environment를 확인한다:

$ sui client envs

다음과 비슷한 output를 보게 된다:

localnet => http://0.0.0.0:9000
testnet => https://fullnode.testnet.sui.io:443 
devnet => https://fullnode.devnet.sui.io:443 (active)

그런 다음 다른 network로 전환해 본다:

$ sui client switch --env testnet

그래도 error가 해결되지 않으면 인터넷 연결을 확인하거나 CLI client를 다시 시작한다.

리소스

Unable to process transaction. Dry run failed, could not automatically determine a budget: UnusedValueWithoutDrop { result_idx: 0, secondary_idx: 0 }​

이 error는 Move transaction에 drop ability가 없거나 이를 명시적으로 drop하지 않았을 때 발생한다. Sui runtime system은 transaction 끝에 값을 사용하지 않은 채 남겨두면 이 error를 발생시키는 resource safety를 강제한다.

해결 방법​

Sui Move package에서는 drop ability가 없는 모든 값을 다른 address로 transfer하거나, 명시적으로 destroy하거나, 다른 function의 input으로 사용해 소비해야 한다.

리소스

Error executing transaction: VMVerificationOrDeserializationError in command 0​

이 error는 Move code가 bytecode verification 중 또는 deserialization 중에 실패함을 나타내는 generic error이다.

해결 방법​

이 error의 일반적인 원인으로는 다음이 있다:

  • ZERO_SIZED_STRUCT: field가 하나도 없는 struct를 정의했다. struct에 field를 하나 이상 추가한다.

  • FIELD_MISSING_TYPE_ABILITY: struct에 key 또는 store 같은 required ability가 없다. 모든 field가 필요한 ability를 가지는지 확인한다.

  • UNKNOWN_VERSION: module 또는 enum이 system이 인식하지 못하는 version 또는 feature를 사용한다. 지원되는 feature와 올바른 Sui toolchain version을 사용하고 있는지 확인한다.

  • CONSTRAINT_NOT_SATISFIED: struct 또는 type parameter가 required ability를 충족하지 않는다. struct 또는 type에 필요한 ability를 추가한다.

  • WRITEREF_WITHOUT_DROP_ABILITY: code가 drop ability가 없는 type에 대한 reference를 쓰려고 한다. type에 drop ability를 추가한다.

리소스

Failed to sign transaction by a quorum of validators because one or more of its objects is reserved for another transaction. Other transactions locking these objects​

이 error는 transaction이 다른 transaction이 이미 사용 중인 Sui object 하나 이상을 사용하려 한다는 뜻이다. transaction에서 object를 사용하면 system은 object를 lock하여 object에 대한 여러 개의 충돌 가능한 수정이 발생하지 않도록 한다. DeFi object의 경우 이는 이중 지출을 방지한다.

해결 방법​

다른 transaction이 완료될 때까지 기다린 다음 transaction을 다시 시도한다. transaction이 멈췄거나 실패했다면 transaction을 다시 시도하기 전에 다음 epoch까지 기다려야 할 수 있다.

code가 여러 object를 동시에 사용하지 않도록 확인한다.

리소스

Failed to sign transaction by a quorum of validators because one or more of its objects is equivocated until the next epoch.​

이 error는 사용하려는 object가 equivocated state에 있음을 나타내며, 이는 충돌하는 transaction 때문에 network가 그 state에 대해 consensus에 도달할 수 없다는 뜻이다. 그 결과 system은 그 object를 freeze하고, 다음 epoch까지 그 object를 사용할 수 없다.

해결 방법​

다음 epoch까지 기다린다.

리소스

Unable to process transaction. Unexpected status code: 403​

이 error는 Sui network가 RPC 또는 API request에 대해 HTTP 403: Forbidden status로 응답함을 나타낸다. 이는 RPC provider가 다음과 같은 경우에 발생할 수 있다:

  • authentication이 필요한데 이를 제공하지 않았다.

  • region 또는 IP를 제한했다.

  • 일정 시간 동안 너무 많은 request를 보내 rate limit를 적용했다.

해결 방법​

필요한 API authentication이 있는지 확인하고 유효한 authentication method를 사용하고 있는지 검증한다. 문서를 검토하여 모든 요구 사항을 따르고 있는지 확인한다.

rate limit 여부를 확인하고 더 긴 시간 간격으로 request를 보내 본다.

Failed to submit transaction: ErrorObject { code: ServerError(-32002), message: "Transaction validator signing failed due to issues with transaction inputs, please review the errors and try again​

이 error는 Sui network가 잘못된 transaction input 때문에 transaction을 거부함을 나타낸다.

해결 방법​

transaction에서 참조하는 모든 object가 다음 조건을 충족하는지 확인한다:

  • 존재한다

  • 현재 version을 사용한다

  • 두 번 참조되지 않는다

  • 최대 object 수라는 protocol limit를 초과하지 않는다.

gas balance가 충분한지, 그리고 transaction signature가 유효한지 확인한다.

Unable to process transaction. No valid gas coins found for the transaction.​

이 error는 transaction gas fee를 지불할 만큼 충분한 token이 없음을 나타낸다.

해결 방법​

token을 확보한다.

리소스