> ## 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](/v2/developers/stellar/troubleshooting/faq)**: Frequently asked questions.
* **[Technical Overview](/v2/developers/stellar/technical-overview)**: Protocol architecture and Soroban fundamentals.
* **[Getting Started](/v2/developers/stellar/getting-started)**: Key differences between EVM and Stellar.