Error handling

The SDK has one error contract: launchExtension throws, the state readers return null.

launchExtension throws

Configuration problems throw before the extension is contacted, with a message naming the missing field (for example Policy ID is required). Communication problems throw during the launch: no extension runtime in the browser, no response within two seconds, or an error reported by the extension itself. The messages are self-descriptive; one catch covers all of them.

try {
  await KeyringConnect.launchExtension(config);
} catch (error) {
  showError(error instanceof Error ? error.message : String(error));
}

State readers return null

getExtensionState resolves to null and isKeyringConnectInstalled resolves to false in every failure case; neither throws. subscribeToExtensionState passes null to the callback when the extension becomes unavailable, which makes an uninstall during the flow observable:

const unsubscribe = KeyringConnect.subscribeToExtensionState((state) => {
  if (!state) {
    // extension unavailable; offer the install path again
    return;
  }
  // handle state.status
});

Proof failures arrive as state

Failures during proving are not thrown; they surface as status: "prove_error" or status: "error" with a message in state.error. The extension gives the user a retry path for each, so the app usually only reflects the state. Causes and fixes are catalogued in extension troubleshooting.