> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerzero.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Errors on Stellar

> Troubleshoot common errors when developing and deploying LayerZero contracts on Stellar Soroban. Includes error codes, causes, and solutions.

## Build Errors

### WASM Compilation Failure

**Error Message:**

```bash wrap theme={null}
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]`:

```rust wrap theme={null}
#![no_std]
use soroban_sdk::{contract, Env};
```

And verify the WASM target is installed:

```bash wrap theme={null}
rustup target add wasm32v1-none
```

### Missing WASM Target

**Error Message:**

```bash wrap theme={null}
error: target `wasm32v1-none` is not installed
```

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

**Solution:**

```bash wrap theme={null}
rustup target add wasm32v1-none
```

## Deployment Errors

### Insufficient Funds

**Error Message:**

```bash wrap theme={null}
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:

```bash wrap theme={null}
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:**

```bash wrap theme={null}
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:**

```bash wrap theme={null}
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:**

```bash wrap theme={null}
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:

```rust wrap theme={null}
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`:

```bash wrap theme={null}
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:

```bash wrap theme={null}
# 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

1. **Check error codes**: Soroban errors include a numeric code. Match it against the error code tables in this page or the contract source.
2. **Simulate first**: Use `stellar contract invoke` with `--send=no` to simulate a transaction without submitting it. This reveals errors before spending fees.
3. **Check events**: Use `stellar events` or the RPC's `getEvents` method to inspect emitted events for debugging.
4. **Verify peers**: Most "message rejected" errors come from misconfigured peers. Always verify peers are set on both sides.
5. **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](https://docs.layerzero.network/v2/developers/stellar/troubleshooting/faq.md)**: Frequently asked questions.
* **[Technical Overview](https://docs.layerzero.network/v2/developers/stellar/technical-overview.md)**: Protocol architecture and Soroban fundamentals.
* **[Getting Started](https://docs.layerzero.network/v2/developers/stellar/getting-started.md)**: Key differences between EVM and Stellar.