Troubleshooting

Keep diagnostic output sanitized. Never paste API keys, consent receipts, runtime tokens, private keys, registry credentials, or full internal responses into tickets.

Package cannot be installed

• Confirm your organization completed private onboarding and received registry or artifact access.
• Verify registry authentication is available to the package-manager process.
• Pin version 1.0.0; the package names are not available from public registries.
• For local artifacts, use the exact Maven repository, npm tarball, NuGet directory, Swift package, or Linux archive layout supplied to your team.

Native library cannot be loaded

• Do not combine wrapper and native files from different releases.
• Node supports only linux-x64 and win32-x64 prebuilds in SDK 1.0.0.
• P2P_SDK_NATIVE_LIB must be an existing absolute path for diagnostic overrides.
• On Linux, run ldd and preserve the SONAME symlink layout.
• On Windows, preserve runtimes/win-x64/native/p2p_sdk.dll or place the DLL beside the executable.
• Verify application and native process architectures match.

Consent window does not open

• API key must be non-empty and the supported wrapper must be used.
• Android requires a visible Activity when a decision must be shown.
• iOS requires a visible UIViewController presenter.
• Electron consent runs in the main process on Electron 28 or newer.
• WPF requires the WebView2 runtime.
• Consent URL must be valid HTTPS and the supplied verification key must be an RS256 public key, not a private key or certificate body.

Consent is accepted but no instance is returned

Inspect status and the sanitized message. Common causes include expired consent state, a version mismatch, an identity mismatch, an invalid public key, inaccurate device time, or an accepted decision generated for another application installation.

No supported wrapper creates a native instance when local verification fails.

Node says consentReceipt is required

consent: true is deprecated. Electron must use @p2psdk/electron; another Node host needs an approved consent receipt source supplied through onboarding. Do not copy an Electron receipt or a receipt from another installation.

connect() succeeds but the app is not online

This is expected while runtime setup is in progress. Wait for connected or observe isOnline.

If connected never arrives:

• Record the disconnected reason and structured error fields.
• Confirm API key and consent state match the current installation.
• Verify device time, TLS trust, DNS, firewall, proxy, and WSS connectivity.
• Confirm package/native versions and target architecture.
• Do not add an application tight-retry loop; the SDK owns connection retry.

Callbacks do not arrive or crash UI code

• Attach handlers before connect().
• Android defaults to the main Handler; verify a custom Executor is alive.
• iOS uses the configured DispatchQueue.
• Node/Electron emits on the JavaScript event loop.
• Direct C callbacks can run on SDK runtime threads and must be marshalled.
• Keep callbacks short and route exceptions to the wrapper error hook or application telemetry.

Revoke fails

• Confirm the onboarding revoke URL is configured before the call.
• Ensure the current instance still owns the same API key and device identity.
• Check network and TLS access.
• Treat non-2xx as failure and keep the active instance for retry.
• Do not delete local state or report success when the wrapper reports failure.

Android background mode stops

• Enable background mode explicitly; notification options alone do not enable it.
• Add required foreground-service permissions and service declaration.
• Request Android 13+ notification permission where applicable.
• Call connect() from an OS-allowed foreground path.
• Force-stop, process death, reboot, and device sleep are not bypassed.

iOS stops in background

Normal iOS suspension policy applies. The SDK does not declare a background mode or guarantee continuous operation. Verify product expectations and reward wording rather than adding unsupported keep-alive behavior.

Electron exits when windows close

Set backgroundMode: true during helper creation and retain the accepted SDK instance. Final disconnect/free releases that session. This setting does not survive force quit or system sleep.

Shutdown hangs or crashes

• Give the instance one owner.
• Stop application work that can call SDK methods before terminal release.
• Clear C callbacks before releasing callback context.
• Call close/free/dispose once and clear the application reference.
• Do not call SDK methods from callbacks after shutdown begins.

If the problem remains, prepare the sanitized support bundle.