Troubleshooting

Start With What You Can See

When the first setup pass fails, do not guess. Start with status, the immediate result from captureInvariantFailure(...), uploadSnapshot.lastErrorCode, and any uploadEvents for the same captureId.

Initialization Throws Or Never Produces A Usable Client

If Revclust.initialize(...) throws, stop there. Log the StateError and fix startup before wiring more triggers.

Status Stays Misconfigured Or Not Provisioned

RevclustStatus.misconfigured means the SDK key is missing, malformed, or otherwise invalid for bootstrap. RevclustStatus.notProvisioned means the key is well-formed but unavailable or revoked. In both cases, capture is blocked and setup should stop. Check Apps, the key status, the copied rpk_... value, and the value injected by your build.

Status Settles At Degraded Or Upload Blocked

RevclustStatus.degraded is not one failure mode. It can mean upload connectivity is unavailable while local queueing still works, or it can mean local capture setup failed before the SDK became usable. RevclustStatus.uploadBlocked means local queueing still works, but upload access is not currently usable.

If you stay in degraded and captureInvariantFailure(...) still returns RevclustCaptureQueued, check reachability and inspect revclust.diagnostics.bootstrap for the last HTTP status, error category, retryability, and safe diagnostic message. If you stay in degraded and captureInvariantFailure(...) returns RevclustCaptureBlocked, treat that as a local capture startup failure. If you stay in uploadBlocked, the likely problem is upload access rather than local capture. In any queueing-allowed case, watch uploadSnapshot.pendingCount and uploadEvents; if work still has not drained after the thirty-second observer window in Verify and Observe, treat the integration as blocked.

Capture Returns Blocked

RevclustCaptureBlocked means no incident was created. The returned status tells you why. disabled means Revclust.initialize(...) has not completed in this app process. initializing means setup is still in flight. misconfigured and notProvisioned mean setup must be corrected before trying again.

If the blocked result occurs while you expect a healthy setup, log the returned message and the current status together.

Capture Builds Or Persists Failed

RevclustCaptureBuildFailed means the invariant failure reached local pack build but failed before it could be queued. RevclustCapturePersistenceFailed means the pack built but could not be stored in the local queue. These are local app or device failures, not backend acceptance failures.

If build fails, inspect the returned message first. If persistence fails, treat the device or simulator runtime as suspect and retry on a clean app process before escalating.

Upload Snapshot Does Not Drain

uploadSnapshot.pendingCount and uploadSnapshot.uploadingCount tell you whether queued work is moving. A healthy first run briefly shows queued work, then active upload, then returns to zero. If counts stay above zero and lastErrorCode remains set, use that error as the coarse boundary:

Upload Events Reject Or Fail

RevclustUploadRejected means the backend made a final decision on the payload. Use the rejection code and message directly in the report.

RevclustTransportFailure means upload failed before the backend accepted or rejected the pack. If retryable is true, the queue will keep trying. If the same failure repeats and the queue does not recover, include the statusCode, message, and current lastErrorCode when you ask for help.

Accepted Pack But Viewer Access Fails

If you receive RevclustUploadAccepted, the backend already accepted the pack. At that point, a missing or inaccessible incident in the viewer is no longer an SDK capture problem. Use the accepted packId or viewerUrl, sign in through revclust.com/get-started, and make sure you are using the right Revclust account for that incident.

What To Include When Escalating

When you need help, report the current status, the immediate capture outcome type, the captureId if one exists, uploadSnapshot.lastErrorCode, and any upload event code or statusCode you observed.

Send that report through your normal Revclust support path. If you are signed into the viewer, Feedback can also include viewer-specific failures such as a missing or inaccessible accepted pack.