Skip to main content

Troubleshooting Common Errors

This page provides troubleshooting solutions to common errors.

Address errors​

Errors in this section relate to Sui addresses.

Failed to build Move modules: Unresolved addresses found.​

You are trying to use a named address, such as std or similar, within your code or a dependency, but you did not assign that address a value in the Move.toml file.

Solution​

Add an entry for each unresolved address to the [addresses] section of your Move.toml file.

[addresses]
std = "0x1"

Resources

Invalid Sui Address​

The address you provided does not conform to a valid Sui address format. Sui addresses must:

  • Be a 32-byte hex-encoded string.

  • Start with 0x and only contain hexadecimal characters (0-9, a-f, A-F).

Solution​

Verify the address you provide starts with 0x, is 64 hex digits long, and does not contain invalid characters.

Resources

Move package errors​

Errors in this section relate to Move packages.

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

This error occurs when your code receives a relative URL (/path/to/file) but expects an absolute URL (https://example.com/path/to/file). This error originates from the sui::url module that provides a Url struct and functions to interact with URLs. Move does not validate the format of a URL itself.

Solution​

Specify the full URL path, including http:// or https://.

Resources

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

The system cannot find one or more of the dependencies you list in your Move package's Move.toml file. The system cannot find a dependency if:

  • Your path is incorrect, contains a typo, or does not exist.

  • Your manifest file does not exist.

  • You have not initialized it properly.

Solution​

Check your Move.toml and verify each dependency you list has the correct path, and each path contains a valid Move.toml file. Ensure there are no typos and that you have initialized all dependencies.

Resources

Duplicate module found: 0x0000000000000000000000000000000000000000000000000000000000000002::groth16​

You have defined two or more modules with the same name or address in your project or its dependencies. Give each module a unique name and address combination.

Solution​

Verify that your source files do not use the same module name or address twice. Check your package's dependencies to see if there is a duplicate name defined. Check if you have a conflicting address assignment in the Move.toml file.

Resources

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

Your environment or tooling cannot find a Move package at the specified address. Possible causes include:

  • You have not published the package to the network.

  • Your address is incorrect.

Solution​

Verify the package exists on the network at the specified address.

Failed to build Move modules: Compilation error.​

Something in your Move code violates the compiler's rules and prevents compilation into bytecode.

Solution​

Some common reasons for this error include:

  • Unbound variable or module: Make sure you declare all modules and variables you reference in your package and they are in scope.

  • Duplicate declaration, item, or annotation: Ensure all functions, structs, and module names are unique within the namespace.

  • Invalid declaration: Always specify an address for a module to properly declare it.

  • Unbound type or member: You must define and import all types and members correctly.

  • Edition not specified: You must define an edition field in all Move.toml files: edition = "2024".

Resources

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

A module in your package does not have the address 0x0. In Move, you must set all modules to have their self-address as 0x0 in the source code. When you publish the package, Sui assigns it the correct address automatically.

Solution​

Remove any explicit address blocks from your Move source files. Do not wrap your modules in address ... { ... } blocks.

Resources

The signer only expects one signature, not two​

A function you are calling in your Move module expects 1 signer argument, yet you provide 2. On Sui, the number of signer arguments in your function's signature must match the number of signers you provide.

Solution​

Verify if you define your function as fun main(s: signer), then you must provide only 1 signer.

If you want to use 2 signers, define your function as fun main(s1: signer, s2: signer) { ... }.

Resources

destroy_zero​

You are trying to destroy a resource that has a non-zero value.

Solution​

Ensure the resource's value is zero. For coins or tokens, split or burn the value until it is zero.

Resources

System errors​

Errors in this section relate to the system.

"Segmentation fault (core dumped)"​

A low-level memory crash occurred. This is not a Move error, but rather an error with a portion of the toolchain such as the Move compiler or a dependency.

Solution​

In some situations, old or corrupted build files can cause this crash. Clean your build:

$ sui move clean

In other scenarios, outdated or mismatched tooling versions might cause this error. Upgrade your tooling and verify that versions match.

Resources

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

This error means that Move cannot access the file or directory due to insufficient permissions.

Solution​

Ensure your user account has the necessary read, write, or execute permissions for the target file or directory.

On Unix and macOS systems, you can edit permissions with the chmod command:

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

This gives you read and write permissions to all files and subdirectories at the specified file path.

Resources

sui move build command hangs​

This behavior often occurs when you run commands on Windows 11 machines.

Solution​

Try using Windows Subsystem for Linux on your Windows machine instead of running commands in a Windows-native terminal.

Resources

Fetch failed error (cause: Header Timeout)​

The network does not receive a response within a certain time period. This error is not specific to Sui.

Solution​

Retry the request or increase the timeout duration if you control the client.

Transaction errors​

Errors in this section relate to transactions.

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

This error occurs when the network is down, your internet connection is unstable, or your Sui client configuration has an error.

Solution​

First determine your client's configured environments:

$ sui client envs

You see something similar to:

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

Then, try switching to another network:

$ sui client switch --env testnet

If this does not resolve the error, check your internet connection or restart your CLI client.

Resources

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

A value in your transaction does not have the drop ability and you did not explicitly consume or transfer it. The Sui runtime enforces resource safety and returns this error when you leave values unused at the end of a transaction.

Solution​

In Sui Move packages, you must either transfer every value that does not have the drop ability to another address, explicitly destroy it, or use it as input for another function to consume.

Resources

Error executing transaction: VMVerificationOrDeserializationError in command 0​

Your Move code might fail either during bytecode verification or during deserialization.

Solution​

Some common reasons for this error include:

  • ZERO_SIZED_STRUCT: You define a struct that has no fields. Add at least one field to the struct.

  • FIELD_MISSING_TYPE_ABILITY: Your struct is missing a required ability such as key or store. Ensure all fields have the necessary abilities.

  • UNKNOWN_VERSION: Your module or enum uses a version or feature the system does not recognize. Ensure you are using supported features and the correct Sui toolchain version.

  • CONSTRAINT_NOT_SATISFIED: Your struct or type parameter does not satisfy the required abilities. Add the required abilities to the struct or type.

  • WRITEREF_WITHOUT_DROP_ABILITY: Your code tries to write a reference to a type that does not have a drop ability. Add the drop ability to the type.

Resources

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​

Indicates that another inflight transaction is already using an object version your transaction also needs. If enough validators have already reserved that object version for a different transaction, your transaction cannot also reserve it.

Solution​

Wait for the first transaction to finish, then rebuild or re-sign the transaction so it uses the latest object references. For related operations, combine them into one programmable transaction block. For parallel execution, use SDK/client helpers that manage gas coins and object dependencies.

Resources

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

Indicates that competing transactions used the same mutable owned object version and validator reservations were split so that no transaction could obtain quorum. The affected object version is unavailable until the next epoch.

Solution​

Wait for the next epoch, then rebuild the transaction using current object references. Avoid submitting multiple concurrent transactions that use the same mutable owned object version. Use independent owned objects for parallel work, combine related operations into one PTB, or use SDK and client helpers that manage gas coins and object dependencies.

Resources

Unable to process transaction. Unexpected status code: 403​

The Sui network responds to an RPC or API request with HTTP 403: Forbidden status. This might happen if an RPC provider:

  • Requires authentication and you do not provide any.

  • Has restricted your region or IP address.

  • Has rate limited you by sending too many requests in a given time period.

Solution​

Check for required API authentication and verify you are using a valid authentication method. Review the documentation to ensure you are following all requirements.

Check for rate limiting and try sending requests over a long period of time.

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​

The Sui network rejects a transaction due to invalid transaction inputs.

Solution​

Ensure all objects you reference in your transaction:

  • Exist

  • Use the current version

  • Are not referenced twice

  • Do not exceed a protocol limit of maximum objects.

Verify you have a sufficient gas balance and that your transaction signature is valid.

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

The sender address either has insufficient SUI balance or the gas coin already serves as a transaction input object.

Solution​
  • Verify the wallet has enough SUI to cover the gas budget.
  • Pass different coin objects for gas payment and transaction input.
  • If you recently sent a transaction, wait for it to finalize before submitting another one that uses the same coin.

Resources

SDK and RPC errors​

Errors in this section relate to the TypeScript SDK, RPC responses, and transaction construction.

Invalid type: Expected Object but received Object​

You wrapped a value already returned by a transaction command (such as tx.splitCoins() or tx.moveCall()) inside tx.object() again. Transaction commands already return values as TransactionArgument objects.

Solution​

Use the return value directly without wrapping it in tx.object():

// Incorrect — double-wrapping causes this error
const coin = tx.splitCoins(tx.gas, [1000]);
tx.transferObjects([tx.object(coin)], recipient); // ❌

// Correct — use the TransactionArgument directly
const coin = tx.splitCoins(tx.gas, [1000]);
tx.transferObjects([coin], recipient); // ✅

Your active environment is not present in Move.toml​

The Sui CLI cannot find the environment alias you use (such as devnet or testnet) in the [environments] section of your Move.toml file.

Solution​

Add an [environments] section to your Move.toml with the environment alias and chain ID:

[environments]
mainnet = { chain-id = "35834a8a" }
testnet = { chain-id = "4c78adac" }

Look up the chain ID for your network with sui client chain-identifier. For local or ephemeral deployments, use sui client test-publish instead.

Resources

RPC error codes​

The Sui RPC layer returns standard error codes. Use the following table to diagnose failures:

CodeNameRetryableCommon cause
-32600Invalid RequestNoMalformed JSON body.
-32601Method Not FoundNoTypo in the RPC method name.
-32602Invalid ParamsNoWrong argument types or missing fields.
-32603Internal ErrorMaybeServer-side failure; retry after backoff.
-32002Transaction Execution ErrorNoOnchain execution failed (MoveAbort).
-32050Transient ErrorYesOverloaded node; retry with exponential backoff.
-32604Timeout ErrorYesRequest timed out; retry after backoff.

Error classification​

Sui errors fall into two categories:

CategoryExamplesWhere it happensWhat to do
Transport errorsHTTP 429/502/504, RPC -32050Network layerRetry with backoff.
Execution errorsMoveAbort, InsufficientGasOnchain VMFix code or parameters.

Detect the category in TypeScript:

import { SuiGrpcClient } from '@mysten/sui/grpc';

const client = new SuiGrpcClient({
  baseUrl: 'https://fullnode.mainnet.sui.io:443',
  network: 'mainnet',
});

try {
  const result = await client.executeTransaction({ /* ... */ });
  // Check execution status from the response
  if (result.effects?.status?.status === 'failure') {
    // On-chain execution error (MoveAbort, InsufficientGas)
    console.error('Execution failed:', result.effects.status.error);
  }
} catch (error) {
  // Transport or infrastructure error
  console.error('RPC error:', error.code, error.message);
}

getPureSerializationType is deprecated​

The getPureSerializationType function is deprecated and might produce unexpected behavior. Using it can cause errors such as Invalid type: Expected Object but received Object.

Solution​

Use explicit typed serialization methods instead:

// Deprecated — do not use
// import { getPureSerializationType } from '@mysten/sui/transactions';

// Use typed methods instead
tx.pure.u64(amount);
tx.pure.address(addr);
tx.pure.string(name);
tx.pure.bool(flag);
tx.pure.vector('u8', bytes);