Troubleshooting
Most integration failures fall into five buckets: provider missing, connection not approved, wallet locked, network mismatch, or invalid request payload.
Provider Missing
Symptom: window.photon is undefined.
Fix: confirm the extension is installed, enabled, and the page was refreshed after installation.
Wallet Connection Rejected
Symptom: connect() rejects with a user-facing approval error.
Fix: treat it as a normal decline path and let the user retry later.
Wallet Locked
Symptom: signing or sending fails even though the extension is installed.
Fix: ask the user to unlock the wallet UI first, then repeat the action.
Network Mismatch
Symptom: transaction requests fail with invalid address or wrong network errors.
Fix: read await photon.getNetwork() before creating the transaction request and validate the destination address for that network.
Quick Diagnostic Snippet
async function diagnosePhoton() {
if (!window.photon) {
return { installed: false };
}
try {
const accounts = await window.photon.getAccounts();
const network = await window.photon.getNetwork().catch(() => null);
return {
installed: true,
connected: accounts.length > 0,
accounts,
network
};
} catch (error) {
return {
installed: true,
error: error.message
};
}
}Common Integration Mistakes
- Calling privileged methods before
connect(). - Sending a mainnet address while the wallet is on testnet or regtest.
- Assuming
signTransaction()returns metadata instead of signed hex. - Assuming
signMessage()is standardized to BIP-322 when it is currently Photon-specific. - Hiding all wallet errors behind one generic “transaction failed” message.
Escalation Path
If your app still fails after basic checks, log the exact method name, the active network, the request payload shape without secrets, and the user-visible error string. That is the minimum useful bug report for diagnosing PhotonBolt Wallet integration issues.