Common Errors on Stellar

Build Errors

WASM Compilation Failure

Error Message:

error[E0463]: can't find crate for `std`

Cause: Soroban contracts target wasm32v1-none which is a no_std environment. Using standard library features that aren’t available. Solution: Ensure your contract crate uses #![no_std]:

#![no_std]
use soroban_sdk::{contract, Env};

And verify the WASM target is installed:

rustup target add wasm32v1-none

Missing WASM Target

Error Message:

error: target `wasm32v1-none` is not installed

Cause: The WASM compilation target is not installed in your Rust toolchain. Solution:

rustup target add wasm32v1-none

Deployment Errors

Insufficient Funds

Error Message:

Error: transaction simulation failed: insufficient funds

Cause: Your account doesn’t have enough XLM to cover the deployment transaction fees and contract storage rent. Solution: Fund your testnet account:

stellar keys fund my-account --network testnet

For mainnet, ensure sufficient XLM balance for the deployment plus storage rent deposit.

Contract Already Exists

Error Message:

Error: contract already exists at address

Cause: A contract with the same deployer/source account and salt already exists at the computed address. Solution: Use a different salt or deployer account. Contract addresses are deterministic based on the deployer and salt.

Constructor Failed

Error Message:

Error: HostError: Error(Contract, #<error_code>)

Cause: The constructor arguments are invalid or a dependency (e.g., endpoint address) is incorrect. Solution: Verify constructor arguments match the contract type: OApp: owner, endpoint, delegate

endpoint must be a valid, deployed Endpoint V2 contract
owner and delegate must be valid addresses

OFT: token, shared_decimals, oft_type, endpoint, delegate

token must be a valid SEP-41 token contract
shared_decimals must be ≤ the token’s local decimals
endpoint must be a valid, deployed Endpoint V2 contract
delegate must be a valid address (serves as the initial owner)

Configuration Errors

No Peer Set

Error Code: 2001 (NoPeer) Cause: Attempted to send a message to a destination that has no configured peer. Solution:

stellar contract invoke \
  --id <YOUR_OAPP_ADDRESS> \
  --network testnet \
  --source my-account \
  -- \
  set_peer \
  --eid <REMOTE_EID> \
  --peer <REMOTE_ADDRESS_BYTES32> \
  --operator <OWNER_ADDRESS>

Only Peer

Error Code: 2002 (OnlyPeer) Cause: Received a message from an address that doesn’t match the configured peer for the source chain. Solution: Verify that the peer address set on this chain matches the actual contract address on the remote chain. Peer addresses must be in 32-byte format (left-padded with zeros for EVM addresses).

Invalid Options

Error Code: 2000 (InvalidOptions) Cause: Enforced options or caller options are malformed or not Type 3 format. Solution: Ensure options follow Type 3 format. Only Type 3 options can be combined. Check that enforced options are set correctly for the destination and message type.

OFT Errors

Slippage Exceeded

Error Code: 3005 (SlippageExceeded) Cause: The received amount after fees and dust removal is below min_amount_ld. Solution: Decrease the min_amount_ld value in your SendParam to allow more slippage tolerance, or reduce OFT fees. Use quote_oft to preview the expected receipt before sending:

let (limit, fees, receipt) = oft.quote_oft(&from, &send_param);
// receipt.amount_received_ld shows what the recipient will get

Invalid Amount

Error Code: 3001 (InvalidAmount) Cause: amount_ld or min_amount_ld is negative. Solution: Ensure both amount_ld and min_amount_ld in SendParam are non-negative.

Paused

Error Code: 3110 (Paused) Cause: The OFT is paused. All send, receive, and quote operations are blocked. Solution: Call unpause from an account that has UNPAUSER_ROLE:

stellar contract invoke \
  --id <OFT_ADDRESS> \
  --network testnet \
  --source my-account \
  -- \
  unpause \
  --operator <OWNER_ADDRESS>

Rate Limit Exceeded

Error Code: 3120 (ExceededRateLimit) Cause: The transfer amount exceeds the configured rate limit capacity. Solution: Wait for capacity to replenish (tokens decay linearly over the configured window), or adjust the rate limit:

# Check current capacity
stellar contract invoke \
  --id <OFT_ADDRESS> \
  --network testnet \
  --source my-account \
  -- \
  rate_limit_capacity \
  --direction Outbound \
  --eid <DST_EID>

Endpoint Errors

Unauthorized

Error Code: 22 (Unauthorized) Cause: The caller is not authorized to perform the action. Could be: not the owner, not the delegate, not the registered library, or require_auth() was not satisfied. Solution: Verify you’re calling from the correct account (owner or delegate) and that your transaction includes the proper authorization.

Path Not Initializable

Error Code: 18 (PathNotInitializable) Cause: The OApp’s allow_initialize_path returned false for the given origin. This means the sender is not a configured peer. Solution: Set the peer on the receiving OApp for the source chain’s endpoint ID.

Payload Hash Not Found

Error Code: 20 (PayloadHashNotFound) Cause: Attempting to clear a message that hasn’t been verified yet, or the payload hash doesn’t match. Solution: Wait for DVN verification to complete before attempting delivery. Use uln302.verifiable(packet_header, payload_hash) to check whether DVNs have reached quorum. If the message is already verifiable but clear still fails, verify that the guid and message exactly match the stored payload, because endpoint.verifiable(origin, receiver) only confirms path and nonce state and does not validate the payload hash used by clear.

ULN-302 Errors

Invalid Config

Error Code: 6 (InvalidConfig) Cause: ULN configuration is malformed (e.g., no DVNs specified, invalid threshold). Solution: Ensure at least one DVN is configured (required or optional). The optional_dvn_threshold must be ≤ the number of optional DVNs.

Duplicate DVNs

Error Code: 5 (DuplicateRequiredDVNs) or 4 (DuplicateOptionalDVNs) Cause: The same DVN address appears multiple times in the configuration. Solution: Remove duplicate DVN addresses from your configuration.

Common Gotchas

TTL Extension During lz_receive

TTL extension during lz_receive introduces additional fees. Ensure the executor gas budget accounts for TTL extension overhead.

Reentrancy Prohibition

Soroban prohibits reentrancy — contracts cannot call themselves (directly or indirectly) in the same transaction. This is why LayerZero uses pull mode for message delivery: the executor calls OApp.lz_receive() directly, and the OApp calls endpoint.clear() internally to verify and clear the payload. This avoids the Endpoint -> OApp -> Endpoint reentrancy that would occur if the Endpoint delivered messages to the OApp directly.

Error Code Reference

Endpoint (1–25)

Code	Name	Description
1	`AlreadyRegistered`	Message library already registered
2	`ComposeExists`	Compose message already exists for this guid/index
3	`ComposeNotFound`	No compose message found for this guid/index
4	`DefaultReceiveLibUnavailable`	No default receive library set for this endpoint ID
5	`DefaultSendLibUnavailable`	No default send library set for this endpoint ID
6	`InsufficientNativeFee`	Native fee provided is below the required amount
7	`InsufficientZroFee`	ZRO fee provided is below the required amount
8	`InvalidExpiry`	Library timeout expiry is invalid
9	`InvalidAmount`	Invalid amount parameter
10	`InvalidIndex`	Compose index is invalid
11	`InvalidNonce`	Nonce does not match expected value
12	`InvalidPayloadHash`	Payload hash does not match the verified hash
13	`InvalidReceiveLibrary`	Receive library is not valid for this OApp/endpoint
14	`OnlyNonDefaultLib`	Operation only allowed on non-default libraries
15	`OnlyReceiveLib`	Library is not registered as a receive library
16	`OnlyRegisteredLib`	Library is not registered
17	`OnlySendLib`	Library is not registered as a send library
18	`PathNotInitializable`	OApp rejected the origin (sender is not a configured peer)
19	`PathNotVerifiable`	Path cannot be verified in its current state
20	`PayloadHashNotFound`	Message not yet verified or payload hash mismatch
21	`SameValue`	Setting the same value that’s already configured
22	`Unauthorized`	Caller is not authorized (not owner, delegate, or registered library)
23	`UnsupportedEid`	Endpoint ID is not supported
24	`ZeroZroFee`	ZRO fee cannot be zero when ZRO payment is selected
25	`ZroUnavailable`	ZRO token is not configured

OApp (2000–2003)

Code	Name	Description
2000	`InvalidOptions`	Options are malformed or not Type 3 format
2001	`NoPeer`	No peer configured for the destination chain
2002	`OnlyPeer`	Inbound message sender does not match configured peer
2003	`ZroTokenUnavailable`	ZRO token not available for fee payment

OFT Core (3000–3005)

Code	Name	Description
3000	`InvalidAddress`	Invalid address format
3001	`InvalidAmount`	Send amount is zero, negative, or rounds to zero after decimal conversion
3002	`InvalidLocalDecimals`	Local decimals < shared decimals
3003	`NotInitialized`	OFT not properly initialized
3004	`Overflow`	Arithmetic overflow
3005	`SlippageExceeded`	Received amount below `min_amount_ld`

OFT Fee Extension (3100–3102)

Code	Name	Description
3100	`InvalidFeeBps`	Fee basis points are outside the allowed range
3101	`InvalidFeeDepositAddress`	Invalid fee deposit address
3102	`SameValue`	Setting the same fee value that’s already configured

OFT Pausable Extension (3110–3111)

Code	Name	Description
3110	`Paused`	OFT is paused
3111	`PauseStatusUnchanged`	Setting pause to its current value

OFT Rate Limiter Extension (3120–3124)

Code	Name	Description
3120	`ExceededRateLimit`	Transfer exceeds rate limit capacity
3121	`InvalidAmount`	Rate limiter amount invalid
3122	`InvalidTimestamp`	Rate limiter timestamp invalid
3123	`InvalidConfig`	Rate limiter config invalid
3124	`SameValue`	Rate limiter same value already set

ULN-302 (1–21)

Code	Name	Description
1	`DefaultExecutorConfigNotFound`	No default executor config for this endpoint ID
2	`DefaultReceiveUlnConfigNotFound`	No default receive ULN config for this endpoint ID
3	`DefaultSendUlnConfigNotFound`	No default send ULN config for this endpoint ID
4	`DuplicateOptionalDVNs`	Same DVN address appears multiple times in optional list
5	`DuplicateRequiredDVNs`	Same DVN address appears multiple times in required list
6	`InvalidConfig`	ULN configuration is malformed (e.g., no DVNs, invalid threshold)
7	`InvalidConfigType`	Unrecognized config type parameter
8	`InvalidConfirmations`	Block confirmations value is invalid
9	`InvalidEID`	Endpoint ID is invalid
10	`InvalidFee`	Fee calculation returned an invalid result
11	`InvalidMessageSize`	Message exceeds maximum allowed size
12	`InvalidOptionalDVNCount`	Number of optional DVNs exceeds the maximum
13	`InvalidOptionalDVNs`	Optional DVN list is invalid
14	`InvalidOptionalDVNThreshold`	Optional DVN threshold exceeds the number of optional DVNs
15	`InvalidRequiredDVNCount`	Number of required DVNs exceeds the maximum
16	`InvalidRequiredDVNs`	Required DVN list is invalid
17	`InvalidSenderAddress`	Sender address format is invalid
18	`UlnAtLeastOneDVN`	At least one DVN (required or optional) must be configured
19	`UnsupportedEid`	Endpoint ID is not supported
20	`Verifying`	Message is still being verified by DVNs
21	`ZeroMessageSize`	Message size cannot be zero

Debugging Tips

Check error codes: Soroban errors include a numeric code. Match it against the error code tables in this page or the contract source.
Simulate first: Use stellar contract invoke with --send=no to simulate a transaction without submitting it. This reveals errors before spending fees.
Check events: Use stellar events or the RPC’s getEvents method to inspect emitted events for debugging.
Verify peers: Most “message rejected” errors come from misconfigured peers. Always verify peers are set on both sides.
Check TTLs: For “entry not found” errors on entries that should exist, the entry may have been archived due to TTL expiry.

Next Steps

FAQ: Frequently asked questions.
Technical Overview: Protocol architecture and Soroban fundamentals.
Getting Started: Key differences between EVM and Stellar.

​Build Errors

​WASM Compilation Failure

​Missing WASM Target

​Deployment Errors

​Insufficient Funds

​Contract Already Exists

​Constructor Failed

​Configuration Errors

​No Peer Set

​Only Peer

​Invalid Options

​OFT Errors

​Slippage Exceeded

​Invalid Amount

​Paused

​Rate Limit Exceeded

​Endpoint Errors

​Unauthorized

​Path Not Initializable

​Payload Hash Not Found

​ULN-302 Errors

​Invalid Config

​Duplicate DVNs

​Common Gotchas

​TTL Extension During lz_receive

​Reentrancy Prohibition

​Error Code Reference

​Endpoint (1–25)

​OApp (2000–2003)

​OFT Core (3000–3005)

​OFT Fee Extension (3100–3102)

​OFT Pausable Extension (3110–3111)

​OFT Rate Limiter Extension (3120–3124)

​ULN-302 (1–21)

​Debugging Tips

​Next Steps

Build Errors

WASM Compilation Failure

Missing WASM Target

Deployment Errors

Insufficient Funds

Contract Already Exists

Constructor Failed

Configuration Errors

No Peer Set

Only Peer

Invalid Options

OFT Errors

Slippage Exceeded

Invalid Amount

Paused

Rate Limit Exceeded

Endpoint Errors

Unauthorized

Path Not Initializable

Payload Hash Not Found

ULN-302 Errors

Invalid Config

Duplicate DVNs

Common Gotchas

TTL Extension During lz_receive

Reentrancy Prohibition

Error Code Reference

Endpoint (1–25)

OApp (2000–2003)

OFT Core (3000–3005)

OFT Fee Extension (3100–3102)

OFT Pausable Extension (3110–3111)

OFT Rate Limiter Extension (3120–3124)

ULN-302 (1–21)

Debugging Tips

Next Steps