Troubleshoot the SDK

Start here when expected sessions do not appear or the SDK cannot send recorded activity. Check one cause at a time so you can identify which change resolves the failure.

Confirm the package source

Open Tools and SDKs in the portal and compare your installed version with the approved package. For a development computer, download the language bundle and use its generated install commands. CI builds use a separate package credential. A similarly named public package is not a substitute.

See Tools and SDKs for download and CI instructions. An application SDK key does not authorize package downloads.

Confirm the target environment

Check these values in the running application:

VERIPROOF_API_KEY contains the complete application credential.
VERIPROOF_APPLICATION_ID identifies the intended VeriProof application.
VERIPROOF_ENDPOINT is unset for hosted VeriProof or points to the assigned private ingest base URL.

Do not split a compound API key yourself. The SDK sends its components in the headers required by the ingest service.

Remove credentials and sensitive data from browser tests, command output, and diagnostic logs. If a key may have been exposed, rotate it from the portal.

Initialize before application work

Configure VeriProof before the application creates OpenTelemetry spans or starts an instrumented framework. If another global tracer provider is already registered, follow the package reference for using the returned tracer instead of registering a second provider.

End and flush work

An exporter can send only completed spans. End each session, activity, or span on both success and error paths. During graceful shutdown, flush or shut down the tracing provider so pending records can be sent.

Check SDK Health

Open the application’s SDK Health view and check:

whether recent sessions arrived;
whether the error rate changed after deployment;
which fields are declared, inferred, or missing.

Send one non-production test session after each configuration change. This keeps the result easy to identify.

Review transport recovery

The SDK opens a circuit after repeated retryable failures and buffers work up to a bounded capacity. Defaults differ by language and version. Use diagnostic logs and the reference for the installed package instead of assuming one shared failure count or reset time.

Authentication and validation failures marked non-retryable require a configuration fix. Waiting will not correct a rejected credential or invalid request.

Confirm the effective control boundary

Open the application’s Control coverage view after a governed-action test.

Wrong environment: the key, application ID, and endpoint must belong to the same deployment.
Invalid or revoked key: rotate the application key and update the running secret. Do not retry a static rejected key indefinitely.
Missing operation: place the protected work inside the documented framework entry point and send a stable operation name.
Observed activity: the adapter recorded telemetry but did not own execution. Add the documented manual wrapper or use an action-owning adapter.
Unsupported stream: buffer output until a supported complete-output check, or do not claim that the stream is governed.
Stale capability evidence: run a new allowed and denied action with the released package. Earlier sessions keep their original meaning.

If the denied action still creates its side effect, stop the rollout. Fix the owning integration boundary before changing the portal display.

Prepare diagnostic details

Include the package name and version, application ID, environment, approximate failure time, and a request or trace ID. Remove credentials, prompt content, response content, and personal data before sharing logs with an authorized reviewer.