Troubleshooting

Production-focused troubleshooting guide for wallet, routing, build, and release issues.

Wallet Address Issues

If you see InvalidAddressError with tb1..., your app is likely reading a Bitcoin address. Ensure you extract STX addresses only.

// good: ST... or SP...
const stxAddress = wallet.accounts?.[0]?.stxAddress;
if (!stxAddress) throw new Error("No STX address found");

lockUntilBlock must be greater than the current chain block when lockAmount > 0. Prefer duration-based UI and compute current + duration.

const current = await vault.getCurrentBlockHeight(sender);
const lockUntil = current + durationBlocks;

Use explicit semantic version bumps (patch/minor/major), then publish after npm authentication and verify with npm view.

npm version patch
npm publish --access public
npm view flowvault-sdk version

Symptom	Likely Cause	Fix
Read call returns parsing error	Contract principal mismatch with deployed network	Verify env vars and redeploy client with correct principal
Deposit tx fails immediately	split + lock amount exceeds deposit value	Validate routing values before send and surface clear UI error
Withdraw fails despite previous deposits	Funds still locked by lock-until block	Poll current block height and retry after unlock height
Build succeeds but runtime points to wrong token	Stale environment variables in deployment target	Check host env configuration and trigger clean redeploy