Troubleshooting

Common issues and how to resolve them.

RPC Connection Errors

Symptom: stellar contract invoke or the metrics exporter fails with a connection error, timeout, or "endpoint not reachable" message.

Causes and fixes:

Wrong RPC URL — verify ROUTER_RPC_URL points to a live Soroban RPC endpoint.
- Testnet: https://soroban-testnet.stellar.org
- Mainnet: https://soroban-mainnet.stellar.org
Network is down — check the Stellar status page.
Firewall or proxy blocking outbound HTTPS — ensure port 443 is open.
Metrics exporter shows no data after startup:
```
docker compose logs metrics-exporter
```
Look for scrape error or connection refused lines. Confirm the contract IDs are set and the RPC URL is reachable from inside the container.

Symptom: A contract call returns NotInitialized or panics with "not initialized".

Cause: The contract's initialize function has not been called after deployment.

Fix: Call initialize with the admin address before any other function:

stellar contract invoke --id <CONTRACT_ID> --network testnet --source admin \
  -- initialize --admin <ADMIN_ADDRESS>

Each contract in the suite requires its own initialize call. Deploy and initialize them in dependency order (see docs/deployment.md).

Note: Calling initialize a second time returns AlreadyInitialized. This is expected — it is a guard against accidental re-initialization.

Symptom: A contract call returns Unauthorized or HostError: auth failed.

Common causes:

Wrong signer — the --source account must match the admin address passed to initialize. Verify with:
```
stellar contract invoke --id <CONTRACT_ID> --network testnet --source admin \
  -- admin
```

Role not granted — for router-access-protected routes, the caller must hold the required role. Grant it first:

stellar contract invoke --id <ACCESS_ID> --network testnet --source admin \
  -- grant_role --caller <ADMIN> --role operator --address <CALLER>

Address is blacklisted — check with has_role and remove the blacklist entry if needed.
Timelock not yet ready — operations queued in router-timelock cannot be executed before their ETA. Check the operation status and wait for the delay to pass.

Symptom: docker compose run tests or docker compose up fails.

Common causes and fixes:

Docker daemon not running:

sudo systemctl start docker
# or on macOS/Windows: start Docker Desktop

Port conflict — Grafana (3000) or Prometheus (9091) already in use:

# Check what is using the port
lsof -i :3000
# Change the port in docker-compose.yml if needed

Missing environment variables for the metrics stack — copy the example file:

cp metrics/.env.example metrics/.env
# Edit metrics/.env and fill in contract IDs

WASM build fails inside the container — the wasm32-unknown-unknown target may not be installed in the image. Rebuild the image:
```
docker compose build --no-cache
```
Tests fail with AlreadyInitialized — each test must use a fresh Env::default() and register a new contract instance. The Soroban test environment is isolated per Env, so this should not happen unless a test helper is reusing state.

wasm32-unknown-unknown target not found:

rustup target add wasm32-unknown-unknown

stellar command not found:

cargo install --locked stellar-cli

cargo build fails with linker errors on Linux: Install the required C toolchain:

sudo apt-get install build-essential

stellar contract deploy fails with "account not found":

Fund your testnet account using Stellar Friendbot:

https://friendbot.stellar.org/?addr=<YOUR_ADDRESS>

Or via the CLI:

stellar keys fund <ACCOUNT_NAME> --network testnet