Troubleshooting¶
Common Theft Shield issues and their solutions.
PSBT Issues¶
PSBTs Invalidated¶
Symptom: Status shows "Needs Attention" or "PSBTs Invalid"
Cause: You made a withdrawal from the wallet (spending to any address, even whitelisted ones).
Note: Deposits don't invalidate PSBTs but reduce coverage percentage since new funds aren't protected by existing PSBTs. Consider regenerating to maintain 100% coverage.
Solution: 1. Go to Theft Shield → Settings 2. Click Regenerate PSBTs 3. Download new unsigned PSBTs 4. Sign with your hardware wallet 5. Upload signed PSBTs
No additional protection fee is required for regeneration.
PSBT Signature Invalid¶
Symptom: Upload rejected with "Invalid signature" error
Causes: - PSBT was modified after signing - Wrong wallet used for signing - Partial signing (not all inputs signed)
Solutions: 1. Re-download fresh unsigned PSBTs 2. Verify you're using the correct hardware wallet 3. Ensure all inputs are signed 4. Try signing again
PSBT Output Mismatch¶
Symptom: "Output address doesn't match safe address"
Cause: The PSBT output doesn't match your configured safe address.
Solution: 1. Verify your safe address in settings 2. Re-download PSBTs (they're generated for your current safe address) 3. Sign and upload again
Setup Issues¶
Cannot Enable Theft Shield¶
Symptom: "Enable Theft Shield" button disabled or errors
Causes: - No UTXOs in wallet - Wallet scan not complete - Subscription tier doesn't support network
Solutions:
| Cause | Solution |
|---|---|
| No UTXOs | Add funds to wallet first |
| Scan incomplete | Wait for scan to complete |
| Wrong tier | Upgrade subscription or use testnet |
Safe Address Rejected¶
Symptom: "Invalid safe address" error
Causes: - Wrong network (mainnet address for testnet wallet) - Invalid address format - Address checksum error
Solution: 1. Verify address is on correct network 2. Double-check for typos 3. Use a fresh address from your safe wallet
Hardware Wallet Issues¶
Coldcard Not Signing¶
Symptom: PSBT appears unsigned after Coldcard process
Solutions:
1. Ensure you pressed ✓ on each transaction
2. Check signed files have -signed suffix
3. Verify correct SD card slot used
4. Try firmware update if persistent
Ledger Connection Issues¶
Symptom: Cannot connect Ledger for signing
Solutions: 1. Ensure Bitcoin app is open on device 2. Try different USB port or cable 3. Update Ledger firmware 4. Use Sparrow/Electrum as bridge
Trezor Timeout¶
Symptom: Signing times out
Solutions: 1. Keep device active during signing 2. Sign fewer PSBTs at once 3. Update Trezor firmware 4. Use Trezor Suite instead of web interface
Monitoring Issues¶
Protection Not Activating¶
Symptom: Theft Shield shows Active but didn't respond to test
Causes: - Transaction went to whitelisted address - Detection delay (rare) - PSBT issue
Debugging: 1. Check if destination was whitelisted 2. Review incident logs 3. Verify PSBTs are valid 4. Contact support if unexplained
False Positives¶
Symptom: Theft Shield triggered on your own transaction
Cause: Transaction destination wasn't whitelisted
Solutions: 1. Add commonly-used addresses to whitelist 2. Pause protection before making unusual transactions 3. Your funds went to your safe address (not lost)
Delayed Detection¶
Symptom: Transaction confirmed before Theft Shield responded
Causes: - Transaction confirmed in next block (unlucky timing) - Detection delay (rare) - Network issues
Note: If a transaction confirms in the very next block after broadcast, there may not be time for Theft Shield to respond. This is a fundamental limitation of RBF-based protection.
Subscription Issues¶
"Feature Not Available"¶
Symptom: Cannot access Theft Shield features
Causes: - On Free tier trying to use mainnet - Subscription expired - Payment issue
Solutions: 1. Use testnet/signet with Free tier 2. Upgrade to Pro for mainnet access 3. Check subscription status in Account settings
Error Messages¶
Common Errors¶
| Error | Meaning | Solution |
|---|---|---|
PSBT_STALE |
UTXOs changed | Regenerate PSBTs |
INVALID_SAFE_ADDRESS |
Address format issue | Re-enter safe address |
SIGNING_ERROR |
Signature problem | Re-sign PSBTs |
UTXO_NOT_FOUND |
UTXO spent or invalid | Check wallet sync status |
BUDGET_EXCEEDED |
Fee budget too low | Increase budget |
NETWORK_MISMATCH |
Wrong network | Check address prefixes |
Error Log¶
For persistent issues, export your error log:
- Go to Theft Shield → Settings
- Click Export Diagnostic Log
- Include log when contacting support
Testing Your Setup¶
Testnet Testing¶
Always test on testnet first:
- Create a testnet wallet
- Get testnet coins from a faucet
- Enable Theft Shield
- Simulate an attack:
- Send transaction to non-whitelisted address
- Verify Theft Shield responds
Verification Checklist¶
- [ ] PSBTs are valid and current
- [ ] Safe address is accessible
- [ ] Whitelist is accurate
- [ ] Notifications are configured
- [ ] Budget is adequate
Getting Help¶
Before Contacting Support¶
- Check this troubleshooting guide
- Export diagnostic log
- Note your wallet ID and recent activity
- Take screenshots of any errors
Contact Support¶
- Email: help@vigilbtc.com
- Nostr: @vigilsupport (npub...)
Include: - Wallet ID - Error messages - What you've tried - Diagnostic log
Back to: Theft Shield Overview →