This guide documents common errors encountered when building, deploying, running, and upgrading LumenFlow smart contracts on Soroban/Stellar. Each entry includes the cause, symptoms, and resolution steps.
For contract-level error codes, see docs/errors.md.
To submit a new error entry, open a PR using the troubleshooting issue template.
Cause: The wasm32-unknown-unknown target has not been added to the active Rust toolchain.
Symptoms:
error[E0463]: can't find crate for `core`
error: cannot find crate for `std`
Resolution:
rustup target add wasm32-unknown-unknownCause: The installed Rust toolchain does not match the version pinned in rust-toolchain.toml.
Symptoms:
error: override file '/workspaces/lumenflow-contracts/rust-toolchain.toml' specifies channel 'stable' but installed toolchain is ...
Resolution:
rustup update stable
rustup override set stableVerify the channel in rust-toolchain.toml matches:
cat rust-toolchain.tomlCause: The soroban-sdk version in contracts/lumenflow/Cargo.toml is incompatible with the active Rust/Soroban toolchain.
Symptoms:
error[E0308]: mismatched types
error: failed to select a version for the requirement `soroban-sdk = "^X.Y"`
Resolution: Align the SDK version with the Stellar CLI and toolchain:
# Check your Stellar CLI version
stellar --version
# Update Cargo.toml to the matching soroban-sdk version, then:
cargo updateSee the Soroban compatibility matrix.
Related error: InvalidInput (50)
Cause: The CI pipeline runs cargo clippy -- -D warnings. Any clippy lint is treated as a hard error.
Symptoms:
error: this expression creates a reference which is immediately dereferenced by the compiler
Resolution: Fix the reported lint, or if it is a false positive, suppress it explicitly:
#[allow(clippy::needless_borrow)]Cause: Code formatting does not match rustfmt defaults. CI runs cargo fmt --all -- --check.
Symptoms:
Diff in contracts/lumenflow/src/lib.rs:
...
Resolution:
cargo fmt --allThen commit the formatted files.
Cause: Soroban enforces a maximum contract WASM size (~128 KB). Adding large dependencies or inlining too much code can breach this.
Symptoms:
error: WasmInvalidImport
or the deploy step rejects the binary.
Resolution:
- Enable
opt-level = "z"andlto = truein the[profile.release]section ofCargo.toml. - Remove unused features from dependencies (
default-features = false). - Run
wasm-opt -Ozon the produced.wasmfile.
Cause: The contract crate inadvertently pulls in std, which is unsupported in a WASM Soroban contract.
Symptoms:
error[E0433]: failed to resolve: use of undeclared crate or module `std`
Resolution: Ensure lib.rs begins with:
#![no_std]and replace any std imports with soroban_sdk equivalents.
Cause: The Stellar RPC node is overloaded or unreachable. Large WASM uploads are particularly susceptible on congested networks.
Symptoms:
Error: RPC request timed out after 30s
Resolution:
- Retry with an exponential back-off:
stellar contract upload --wasm target/wasm32-unknown-unknown/release/lumenflow.wasm \ --rpc-url https://soroban-testnet.stellar.org --network-passphrase "Test SDF Network ; September 2015" - Try an alternative public RPC endpoint.
- Increase the CLI timeout via the
STELLAR_RPC_TIMEOUTenvironment variable (if supported by your CLI version).
Cause: The deploying account's XLM balance is too low to cover the resource fees for uploading and instantiating the contract.
Symptoms:
Error: insufficient balance
or
InsufficientBalance (error code 25)
Resolution:
- Testnet: Fund via Friendbot.
- Mainnet: Transfer XLM to the deployer account before running
deploy.sh.
Cause: Friendbot enforces a per-address and per-IP rate limit. Multiple rapid requests hit the cap.
Symptoms:
{"detail":"Please try again later."}
Resolution:
- Wait 60 seconds and retry.
- Use a different address for each test run, or pre-fund a pool of test accounts.
- For CI, fund accounts once in a setup step and reuse them across tests.
Cause: The contract was re-compiled (even without source changes) and the resulting WASM hash differs from the previously deployed hash stored on-chain.
Symptoms:
Error: contract hash mismatch
Resolution:
- Always use
--ignore-checksonly if you are certain of the binary identity. - Use deterministic builds: pin the Rust toolchain (
rust-toolchain.toml) and all dependency versions (Cargo.lock) so the same source always produces the same WASM. - Verify the hash before deploying:
sha256sum target/wasm32-unknown-unknown/release/lumenflow.wasm
Cause: Calling set_admin on a contract that already has an admin stored in persistent storage. Error code 2.
Symptoms:
Error: AdminAlreadySet (2)
Resolution: set_admin is a one-time initialisation call. If you need to change the admin, implement or call an upgrade/migration path. For fresh testnet deploys, deploy a new contract instance and call set_admin on it.
Cause: Docker Desktop is not running, or the Stellar container image is not pulled.
Symptoms:
Error response from daemon: No such container: stellar
stellar network container start local: exit status 1
Resolution:
# Ensure Docker is running, then:
stellar network container start local
# If the container already exists in a bad state:
stellar network container stop local
stellar network container start local
# Or restart:
stellar network container restart localCause: The SOURCE_ACCOUNT environment variable passed to deploy.sh is not a valid Stellar secret key (S…).
Symptoms:
Error: invalid source account
Resolution:
# Generate a new keypair for local/testnet use:
stellar keys generate --network testnet my-deployer
stellar keys show my-deployer
export SOURCE_ACCOUNT=$(stellar keys show my-deployer --secret-key)Cause: The caller's address does not match the stored admin address. Error code 1.
Symptoms:
Error: Unauthorized (1)
Resolution:
- Verify you are signing with the correct admin key:
stellar contract invoke ... --source-account $ADMIN_KEY -- get_merchant ... - Confirm the admin address stored on chain:
stellar contract invoke --id $CONTRACT_ID --source-account $CALLER_KEY --network $NETWORK \ -- get_global_payment_stats --admin <expected-admin>
Cause: The merchant address passed to process_payment_with_signature has not been registered, or was deactivated. Error code 10.
Symptoms:
Error: MerchantNotFound (10)
Resolution:
# Check if merchant is registered
stellar contract invoke --id $CONTRACT_ID --source-account $CALLER_KEY --network $NETWORK \
-- get_merchant --merchant_address <address>
# If not found, register first:
stellar contract invoke ... -- register_merchant ...Cause: The ed25519 signature passed to process_payment_with_signature does not verify against the merchant's public key and the payment payload. Error code 23.
Symptoms:
Error: InvalidSignature (23)
Resolution:
- Ensure the signature covers the correct payload (order_id + amount + merchant_address).
- Use the merchant's ed25519 private key to sign and the corresponding public key in the call.
- Verify byte ordering — Stellar uses big-endian 32-byte keys.
Cause: An order with the same order_id was already processed successfully. Error code 21.
Symptoms:
Error: PaymentAlreadyExists (21)
Resolution: Use unique order IDs per transaction. Include a timestamp or UUID:
const orderId = `ORDER_${Date.now()}_${crypto.randomUUID()}`;Cause: More than 30 days have elapsed since paid_at for the payment. Error code 32.
Symptoms:
Error: RefundWindowExpired (32)
Resolution: Refunds must be initiated within 30 days. Communicate this policy to customers at checkout. There is no on-chain override; the window is enforced by the contract.
Cause: The cumulative refund amount for an order would exceed the original payment amount. Error code 33.
Symptoms:
Error: RefundExceedsOriginal (33)
Resolution: Track the already-refunded amount off-chain and ensure each refund request is for original_amount - already_refunded.
Cause: execute_multisig_payment was called before the required number of signers had signed. Error code 43.
Symptoms:
Error: InsufficientSignatures (43)
Resolution: Check the current signature count before executing:
stellar contract invoke ... -- get_multisig_payment --payment_id "MS_001"Wait for the remaining signers to call sign_multisig_payment.
Cause: The limit parameter exceeds 100 (the maximum allowed). Error code 51.
Symptoms:
Error: PaginationLimitExceeded (51)
Resolution: Use cursor-based pagination with limit ≤ 100:
# Page 1
stellar contract invoke ... -- get_merchant_payment_history \
--merchant <addr> --cursor null --limit 100 ...
# Page 2 — use the last order_id from page 1 as the cursor
stellar contract invoke ... -- get_merchant_payment_history \
--merchant <addr> --cursor "LAST_ORDER_ID" --limit 100 ...Cause: An admin has deactivated the merchant. Payments and new refunds for inactive merchants are rejected. Error code 12.
Symptoms:
Error: MerchantInactive (12)
Resolution: Contact your platform admin to re-activate the merchant account, or register a new merchant address.
Cause: The payment record has been cleaned up by cleanup_expired_payments after the configured cleanup period. Error code 24.
Symptoms:
Error: PaymentExpired (24)
Resolution: Archive payments proactively before they expire, or increase the cleanup period:
stellar contract invoke ... -- set_payment_cleanup_period --admin <admin> --period 15552000Cause: The transaction simulation step (run before submission) encountered a contract trap, such as a panic or an out-of-bounds ledger access.
Symptoms:
HostError: Error(Contract, #X)
Resolution:
- Enable
RUST_BACKTRACE=1and re-run. - Check the Soroban diagnostic events in the response for the precise error code.
- Cross-reference the code with
error.rs.
Cause: A contract upgrade changes the layout of a persistent storage key. Old data is read with a new type, causing a deserialization panic.
Symptoms:
HostError: Error(Value, InvalidInput)
Resolution:
- Write an explicit migration function before deploying the new WASM.
- Use versioned storage keys (e.g.,
DataKey::MerchantV2) and migrate data lazily on first access. - Test upgrades on a testnet fork with production data snapshots before mainnet.
Cause: The release workflow calls wasm-opt for binary optimisation but the tool is not installed in the CI runner.
Symptoms:
/bin/sh: wasm-opt: command not found
Resolution: Add a step to install binaryen before the build step in the workflow:
- name: Install binaryen
run: |
sudo apt-get update && sudo apt-get install -y binaryenCause: Running stellar contract deploy creates a new contract instance. Existing integrations pointing to the old contract ID break.
Symptoms: Old clients receive PaymentNotFound or MerchantNotFound because they are talking to an empty contract.
Resolution: Use stellar contract upload (to upload new WASM) followed by the upgrade mechanism of the existing contract, not a fresh deploy. Keep the contract ID stable.
Cause: A critical security finding was patched, requiring a re-audit before the new WASM can be deployed to mainnet.
Symptoms: Mainnet deployment is blocked by the audit policy in docs/audit/.
Resolution: Engage the audit firm for a targeted re-review of the changed functions. Do not deploy to mainnet until the re-audit sign-off is received. See docs/audit/audit-report-v1.0.md.
Found an error not listed here? Please open a PR using the troubleshooting entry template and follow the format:
### X-NN — Short error title
**Cause:** What causes this.
**Symptoms:**
\```
Error message or log output
\```
**Resolution:** How to fix it.Link to the relevant error code in docs/errors.md where applicable.