Documentation
Troubleshooting
Start With What You Can See
When initial setup 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 wait 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 incident could not be assembled for queueing. RevclustCapturePersistenceFailed means the incident was assembled but could not be stored in the local queue. These are local app or device failures, not service 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 contacting support.
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:
RevclustUploadErrorCode | What to check next |
|---|---|
transportUnavailable | Upload connectivity is unavailable. Check reachability and retry later. |
auth | Upload access is blocked or expired. Recheck setup. |
misconfiguration | The SDK key is not usable for this setup. Stop and correct the config. |
invalidRequest | The upload payload or request shape was rejected. Check the upload rejection code and message. |
quotaExceeded | The workspace has reached its captured-incident allowance. Check Usage and billing for the current plan and usage. |
unsupportedSchema | The backend rejected the schema version. Verify the shipped SDK version and compatibility. |
blobTooLarge | The capture exceeded current size limits. Reduce captured scope or contact support about its size. |
internalError | Local capture or the backend failed unexpectedly. Include the visible event codes when contacting support. |
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 service accepted or rejected the capture. 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 Incident But Viewer Access Fails
If you receive RevclustUploadAccepted, the service already accepted the incident. 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 Contacting Support
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 to support@revclust.com. After signing in, you can also report viewer-specific issues such as a missing or inaccessible accepted incident through Feedback.