Troubleshooting

403 agent_not_allowed_for_share

Agent is not in share allow-list. Resolve with a permitted agent or recreate share policy including this agent.

401 invalid_grant

Grant is missing, malformed, or expired. Re-run resolve → grant and retry fetch with new X-Access-Grant.

409 grant_already_used

Grant tokens are one-use. Mint a fresh grant for each protected fetch retry.

404 share_not_found_or_expired

Share TTL elapsed or ID is invalid. Re-upload or generate a new share with appropriate TTL.

Operational Debugging

Use console/runtime logs as the source of truth. BetterStack is a non-blocking search sink, so fall back to platform console logs whenever ingestion is delayed.

Start with requestId, then collect targetType, targetId, transferLane, status or doStatus, and the bounded reason field. Search http.request.start, confirm transfer.lane.selected, follow the relevant lifecycle event, and close the loop with http.request.end.

• File upload: inspect file.upload.ok and file.upload.rejected; reasons include rate_limit, missing_file_body, file_too_large, and daily_quota_exceeded.
• File download/delete: inspect file.download.rejected and file.delete.rejected; reasons include invalid_file_download_session, target_not_found_or_expired, range_not_satisfiable, storage_object_missing, delete_authorization_failed, and target_not_found.
• Folder upload/finalize: inspect folder.upload.rejected and folder.finalize.rejected; reasons include folder_not_found, upload_not_allowed, file_too_large, folder_encryption_required, daily_quota_exceeded, and folder_upload_incomplete.
• Folder download/delete: inspect folder.download.rejected, folder.zip.rejected, and folder.delete.rejected; reasons include file_not_found, file_not_ready, range_not_satisfiable, storage_object_missing, no_ready_files, encrypted_zip_unavailable, and delete_authorization_failed.
• Multipart upload: inspect multipart.init.rejected, multipart.part.rejected, multipart.complete.rejected, and multipart.delete.rejected; reasons include filename_required, file_too_large, missing_part_headers, missing_part_body, multipart_upload_not_found, r2_upload_failed, daily_quota_exceeded, and delete_authorization_failed.
• Direct multipart: inspect multipart.direct.init.rejected, multipart.direct.authorize.rejected, and multipart.direct.complete.rejected; reasons include direct_r2_multipart_unavailable, invalid_direct_authorize_request, direct_authorize_too_many_parts, direct_multipart_upload_not_found, direct_part_verification_failed, and daily_quota_exceeded.
• Progressive upload: inspect progressive.init.rejected, progressive.commit.rejected, progressive.complete.rejected, and progressive.delete.rejected; reasons include progressive_r2_unavailable, file_too_large, daily_quota_exceeded, progressive_upload_not_found, progressive_chunk_not_visible, progressive_chunk_size_mismatch, progressive_upload_incomplete, and delete_authorization_failed.
• Progressive receive: inspect progressive.download-session.rejected, progressive.download-chunks.rejected, and progressive.download-complete.rejected; reasons include progressive_access_denied, invalid_progressive_download_session, progressive_download_too_many_chunks, progressive_chunk_not_downloadable, and progressive_download_incomplete.
• Pipe create/delete: inspect pipe.create.rejected, pipe.create.failed, and pipe.delete.rejected; reasons include rate_limit, filename_required, auth_required_for_agent, do_init_failed, and delete_authorization_failed.
• Pipe send: inspect pipe.push.forwarded, pipe.push.rejected, pipe.done.forwarded, and pipe.done.rejected.
• Pipe receive: inspect pipe.stream.forwarded and pipe.stream.rejected.
• TUS resume: inspect tus.patch.rejected and tus.delete.rejected; reasons include offset_mismatch, missing_patch_body, daily_quota_exceeded, and tus_upload_not_found.
• Cleanup: group cleanup.sweep.start, cleanup.record.cleaned, cleanup.record.failed, and cleanup.scheduled.run by sweepId.
• Browser-side evidence: inspect delivery.telemetry for final reason, effective Mbps, retry count, backpressure delay, browser, and device class.
• Operational counters: aggregate operational.transfer.counters by transferLane; sum completionRateNumerator and completionRateDenominator, then inspect retryDensity, backpressureDensity, and effectiveMbps.