Add troubleshooting & monitoring section#105
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis PR adds a new comprehensive Troubleshooting & Monitoring documentation section with guides for analytics events, enabling troubleshooting mode, and failure reasons. It also updates existing log event documentation with a clarification note distinguishing client-side from server-side events. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Tip 🧪 Unit Test Generation v2 is now available!We have significantly improved our unit test generation capabilities. To enable: Add this to your reviews:
finishing_touches:
unit_tests:
enabled: trueTry it out by using the Have feedback? Share your thoughts on our Discord thread! Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 10
🤖 Fix all issues with AI agents
In `@content/docs/troubleshooting/analytics-event.mdx`:
- Around line 146-154: The comment for the metadata field references a
nonexistent LogType value PROOF_GENERATED; update the documentation to match the
actual union member PROOF_GENERATION_SUCCESS (or rename the LogType member to
PROOF_GENERATED if that semantic is preferred) so the listed parsing cases align
with the code; specifically edit the comment near the metadata: string
declaration and ensure the examples list uses PROOF_GENERATION_SUCCESS,
LOGIN_DETECTED, FETCHED_PROVIDERS, and RECLAIM_EXCEPTION to match the LogType
union.
- Around line 20-25: The JSON example uses TypeScript-like unquoted keys and
type annotations; replace it with valid JSON by quoting keys "message" and
"data", providing a string value for "message" (e.g., "string") and an array for
"data" (e.g., empty array or sample objects conforming to AnalyticsLogEntry) so
the snippet parses as JSON; update the example that currently shows message:
string and data: AnalyticsLogEntry[] to use "message": "string" and "data": []
(or a sample array of AnalyticsLogEntry objects).
In `@content/docs/troubleshooting/index.mdx`:
- Line 106: Fix the typo in the documentation sentence that contains
"Troubleshooting Mode" by replacing "specificually" with "specifically" so the
line reads: 'If a user is facing issues in the wild, you can ask them to
specifically enable "Troubleshooting Mode" in the Verifier UI.' Locate the
sentence with "Troubleshooting Mode" and correct the misspelling.
- Line 78: The relative link in content/docs/troubleshooting/index.mdx currently
points to "./troubleshooting/analytics-event" which duplicates the directory;
update the href for the link text "[**Read the full Analytics Events Guide →**]"
to "./analytics-event" (remove the redundant "troubleshooting/" prefix) so the
link correctly resolves to the Analytics Events Guide in the same directory.
- Line 50: The sentence contains a typo: replace "scenarious" with "scenarios"
in the text that reads "This is useful for scenarious where your user wishes to
use alternative verification method during verification journey"; also adjust
minor grammar by adding "a" before "verification journey" so the final text
reads "...scenarios where your user wishes to use an alternative verification
method during a verification journey." Target the exact sentence in
content/docs/troubleshooting/index.mdx and update the word and articles as
described.
- Line 108: Link "[**How to Enable Troubleshooting Mode
→**](./troubleshooting/enable-troubleshooting-mode)" is broken; update that
reference to the actual existing doc path (for example add the extension or
correct relative depth — e.g.,
"./troubleshooting/enable-troubleshooting-mode.mdx" or
"../troubleshooting/enable-troubleshooting-mode" depending on where the target
file lives) so it resolves correctly, then verify by running the docs build or
preview to ensure the link points to the intended page.
- Around line 29-34: The JSON example in the code block uses TypeScript-style
annotations (e.g., "string", [key: any]: any) which are invalid JSON; update the
code block under the troubleshooting example to either (a) use valid JSON values
(e.g., "type": "ReclaimVerificationAbortedException", "message": "User cancelled
the verification") or (b) change the fenced block language to TypeScript/TSX and
keep the current shape; edit the JSON code block content accordingly so the
example is syntactically correct and the fenced-block language matches the
content.
- Around line 43-46: The two links in this file reference
"./troubleshooting/analytics-event" (and the fragment) but this file already
lives in the troubleshooting directory, so update both occurrences to remove the
redundant "troubleshooting/" prefix (e.g., change [fetching analytics
events](./troubleshooting/analytics-event) → ./analytics-event and [Analytics
Events](./troubleshooting/analytics-event#description-of-reclaim_exception-in-metadata)
→ ./analytics-event#description-of-reclaim_exception-in-metadata) to ensure they
resolve correctly; edit the link targets used in the current MDX content where
those exact link texts appear.
- Line 118: The relative link target
"./troubleshooting/potential-failure-reasons" in the link "[**View Potential
Failure Reasons →**]" is broken; update the href to the correct path (for
example add the file extension or adjust the relative path to match the actual
file location, e.g. "./troubleshooting/potential-failure-reasons.mdx" or
"../troubleshooting/potential-failure-reasons") and verify the target file
exists so the link resolves correctly.
In `@content/docs/troubleshooting/potential-failure-reasons.mdx`:
- Line 26: The heading "### Outdated Operating System 낡" contains an unintended
Korean character "낡"; remove that character or replace it with the intended
emoji (or nothing) so the heading reads cleanly (e.g., "### Outdated Operating
System" or "### Outdated Operating System ⚠️"); update the heading line in the
document (the heading text shown) accordingly.
🧹 Nitpick comments (2)
content/docs/troubleshooting/enable-troubleshooting-mode.mdx (1)
1-4: Consider using a meaningful description instead of a date.The
descriptionfrontmatter field typically contains a brief summary of the page content for SEO and previews, not a "Last updated" date. Consider moving the date to the page body or using a proper description.📝 Proposed fix
--- title: How to Enable Troubleshooting Mode - Reclaim Protocol -description: Last updated December 9, 2025 +description: Step-by-step guide to enable troubleshooting mode for debugging verification issues ---content/docs/troubleshooting/potential-failure-reasons.mdx (1)
1-4: Consider using a meaningful description instead of a date.Same as the previous file - the
descriptionfield should contain a brief summary for SEO purposes rather than a "Last updated" date.📝 Proposed fix
--- title: Potential Failure Reasons - Reclaim Protocol -description: Last updated August 20, 2025 +description: Common reasons why verification may fail and how to address them ---
| ```json | ||
| { | ||
| message: string; | ||
| data: AnalyticsLogEntry[]; | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Invalid JSON syntax in the example.
JSON requires double-quoted keys. The current example uses unquoted keys which would fail to parse.
📝 Proposed fix
```json
{
- message: string;
- data: AnalyticsLogEntry[];
+ "message": "string",
+ "data": []
}</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🤖 Prompt for AI Agents
In `@content/docs/troubleshooting/analytics-event.mdx` around lines 20 - 25, The
JSON example uses TypeScript-like unquoted keys and type annotations; replace it
with valid JSON by quoting keys "message" and "data", providing a string value
for "message" (e.g., "string") and an array for "data" (e.g., empty array or
sample objects conforming to AnalyticsLogEntry) so the snippet parses as JSON;
update the example that currently shows message: string and data:
AnalyticsLogEntry[] to use "message": "string" and "data": [] (or a sample array
of AnalyticsLogEntry objects).
| /** | ||
| * Contains stringified JSON or an empty string. | ||
| * Parse this string and cast based on logType: | ||
| * - PROOF_GENERATED -> MetadataProofGenerated | ||
| * - LOGIN_DETECTED -> MetadataLogin | ||
| * - FETCHED_PROVIDERS -> MetadataFetchedProviders | ||
| * - RECLAIM_EXCEPTION -> MetadataReclaimException | ||
| */ | ||
| metadata: string; |
There was a problem hiding this comment.
Mismatch between comment and LogType values.
The comment at line 149 references PROOF_GENERATED, but the LogType union only defines PROOF_GENERATION_SUCCESS. This could confuse developers trying to parse metadata based on the documented types.
📝 Proposed fix
* Parse this string and cast based on logType:
- * - PROOF_GENERATED -> MetadataProofGenerated
+ * - PROOF_GENERATION_SUCCESS -> MetadataProofGenerated
* - LOGIN_DETECTED -> MetadataLogin📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| /** | |
| * Contains stringified JSON or an empty string. | |
| * Parse this string and cast based on logType: | |
| * - PROOF_GENERATED -> MetadataProofGenerated | |
| * - LOGIN_DETECTED -> MetadataLogin | |
| * - FETCHED_PROVIDERS -> MetadataFetchedProviders | |
| * - RECLAIM_EXCEPTION -> MetadataReclaimException | |
| */ | |
| metadata: string; | |
| /** | |
| * Contains stringified JSON or an empty string. | |
| * Parse this string and cast based on logType: | |
| * - PROOF_GENERATION_SUCCESS -> MetadataProofGenerated | |
| * - LOGIN_DETECTED -> MetadataLogin | |
| * - FETCHED_PROVIDERS -> MetadataFetchedProviders | |
| * - RECLAIM_EXCEPTION -> MetadataReclaimException | |
| */ | |
| metadata: string; |
🤖 Prompt for AI Agents
In `@content/docs/troubleshooting/analytics-event.mdx` around lines 146 - 154, The
comment for the metadata field references a nonexistent LogType value
PROOF_GENERATED; update the documentation to match the actual union member
PROOF_GENERATION_SUCCESS (or rename the LogType member to PROOF_GENERATED if
that semantic is preferred) so the listed parsing cases align with the code;
specifically edit the comment near the metadata: string declaration and ensure
the examples list uses PROOF_GENERATION_SUCCESS, LOGIN_DETECTED,
FETCHED_PROVIDERS, and RECLAIM_EXCEPTION to match the LogType union.
| { | ||
| "type": "string", | ||
| "message": "string", | ||
| [key: any]: any | ||
| } | ||
| ``` |
There was a problem hiding this comment.
JSON example uses TypeScript syntax.
The JSON code block contains TypeScript type annotations (string, any) which aren't valid JSON. Consider using a realistic example or switching to TypeScript syntax highlighting.
📝 Proposed fix - use realistic JSON example
```json
{
- "type": "string",
- "message": "string",
- [key: any]: any
+ "type": "ReclaimVerificationAbortedException",
+ "message": "User cancelled the verification"
}</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In @content/docs/troubleshooting/index.mdx around lines 29 - 34, The JSON
example in the code block uses TypeScript-style annotations (e.g., "string",
[key: any]: any) which are invalid JSON; update the code block under the
troubleshooting example to either (a) use valid JSON values (e.g., "type":
"ReclaimVerificationAbortedException", "message": "User cancelled the
verification") or (b) change the fenced block language to TypeScript/TSX and
keep the current shape; edit the JSON code block content accordingly so the
example is syntactically correct and the fenced-block language matches the
content.
</details>
<!-- fingerprinting:phantom:poseidon:ocelot -->
<!-- This is an auto-generated comment by CodeRabbit -->
| Other errors (such as network timeouts or internal exceptions) will **not** trigger this callback but can be found by [fetching analytics events](./troubleshooting/analytics-event) for the session. | ||
|
|
||
| > [!TIP] | ||
| > For a comprehensive list of all possible backend exceptions, refer to the [Analytics Events](./troubleshooting/analytics-event#description-of-reclaim_exception-in-metadata). |
There was a problem hiding this comment.
Broken relative links - redundant path prefix.
These links use ./troubleshooting/ but this file is already in the troubleshooting directory. The links will resolve to a non-existent nested path.
📝 Proposed fix
-Other errors (such as network timeouts or internal exceptions) will **not** trigger this callback but can be found by [fetching analytics events](./troubleshooting/analytics-event) for the session.
+Other errors (such as network timeouts or internal exceptions) will **not** trigger this callback but can be found by [fetching analytics events](./analytics-event) for the session.
> [!TIP]
-> For a comprehensive list of all possible backend exceptions, refer to the [Analytics Events](./troubleshooting/analytics-event#description-of-reclaim_exception-in-metadata).
+> For a comprehensive list of all possible backend exceptions, refer to the [Analytics Events](./analytics-event#description-of-reclaim_exception-in-metadata).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Other errors (such as network timeouts or internal exceptions) will **not** trigger this callback but can be found by [fetching analytics events](./troubleshooting/analytics-event) for the session. | |
| > [!TIP] | |
| > For a comprehensive list of all possible backend exceptions, refer to the [Analytics Events](./troubleshooting/analytics-event#description-of-reclaim_exception-in-metadata). | |
| Other errors (such as network timeouts or internal exceptions) will **not** trigger this callback but can be found by [fetching analytics events](./analytics-event) for the session. | |
| > [!TIP] | |
| > For a comprehensive list of all possible backend exceptions, refer to the [Analytics Events](./analytics-event#description-of-reclaim_exception-in-metadata). |
🤖 Prompt for AI Agents
In `@content/docs/troubleshooting/index.mdx` around lines 43 - 46, The two links
in this file reference "./troubleshooting/analytics-event" (and the fragment)
but this file already lives in the troubleshooting directory, so update both
occurrences to remove the redundant "troubleshooting/" prefix (e.g., change
[fetching analytics events](./troubleshooting/analytics-event) →
./analytics-event and [Analytics
Events](./troubleshooting/analytics-event#description-of-reclaim_exception-in-metadata)
→ ./analytics-event#description-of-reclaim_exception-in-metadata) to ensure they
resolve correctly; edit the link targets used in the current MDX content where
those exact link texts appear.
|
|
||
| ### Handle 'Verify Another Way' | ||
|
|
||
| When the 'Verify Another Way' option is enabled for your app in the user-facing UI, you can decide what URL opens when the user presses this button. You can also trigger a callback to your backend. This is useful for scenarious where your user wishes to use alternative verification method during verification journey |
There was a problem hiding this comment.
Typo: "scenarious" should be "scenarios".
📝 Proposed fix
-When the 'Verify Another Way' option is enabled for your app in the user-facing UI, you can decide what URL opens when the user presses this button. You can also trigger a callback to your backend. This is useful for scenarious where your user wishes to use alternative verification method during verification journey
+When the 'Verify Another Way' option is enabled for your app in the user-facing UI, you can decide what URL opens when the user presses this button. You can also trigger a callback to your backend. This is useful for scenarios where your user wishes to use an alternative verification method during the verification journey.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| When the 'Verify Another Way' option is enabled for your app in the user-facing UI, you can decide what URL opens when the user presses this button. You can also trigger a callback to your backend. This is useful for scenarious where your user wishes to use alternative verification method during verification journey | |
| When the 'Verify Another Way' option is enabled for your app in the user-facing UI, you can decide what URL opens when the user presses this button. You can also trigger a callback to your backend. This is useful for scenarios where your user wishes to use an alternative verification method during the verification journey. |
🧰 Tools
🪛 LanguageTool
[grammar] ~50-~50: Ensure spelling is correct
Context: ...ack to your backend. This is useful for scenarious where your user wishes to use alternati...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
In `@content/docs/troubleshooting/index.mdx` at line 50, The sentence contains a
typo: replace "scenarious" with "scenarios" in the text that reads "This is
useful for scenarious where your user wishes to use alternative verification
method during verification journey"; also adjust minor grammar by adding "a"
before "verification journey" so the final text reads "...scenarios where your
user wishes to use an alternative verification method during a verification
journey." Target the exact sentence in content/docs/troubleshooting/index.mdx
and update the word and articles as described.
|
|
||
| You can fetch these events using the Session ID. | ||
|
|
||
| [**Read the full Analytics Events Guide →**](./troubleshooting/analytics-event) |
There was a problem hiding this comment.
Broken relative link.
Same issue - remove the redundant troubleshooting/ prefix.
📝 Proposed fix
-[**Read the full Analytics Events Guide →**](./troubleshooting/analytics-event)
+[**Read the full Analytics Events Guide →**](./analytics-event)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| [**Read the full Analytics Events Guide →**](./troubleshooting/analytics-event) | |
| [**Read the full Analytics Events Guide →**](./analytics-event) |
🤖 Prompt for AI Agents
In `@content/docs/troubleshooting/index.mdx` at line 78, The relative link in
content/docs/troubleshooting/index.mdx currently points to
"./troubleshooting/analytics-event" which duplicates the directory; update the
href for the link text "[**Read the full Analytics Events Guide →**]" to
"./analytics-event" (remove the redundant "troubleshooting/" prefix) so the link
correctly resolves to the Analytics Events Guide in the same directory.
|
|
||
| ## Troubleshooting Mode | ||
|
|
||
| If a user is facing issues in the wild, you can ask them to specificually enable "Troubleshooting Mode" in the Verifier UI. This displays a debug overlay and captures additional diagnostics. |
There was a problem hiding this comment.
Typo: "specificually" should be "specifically".
📝 Proposed fix
-If a user is facing issues in the wild, you can ask them to specificually enable "Troubleshooting Mode" in the Verifier UI. This displays a debug overlay and captures additional diagnostics.
+If a user is facing issues in the wild, you can ask them to specifically enable "Troubleshooting Mode" in the Verifier UI. This displays a debug overlay and captures additional diagnostics.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| If a user is facing issues in the wild, you can ask them to specificually enable "Troubleshooting Mode" in the Verifier UI. This displays a debug overlay and captures additional diagnostics. | |
| If a user is facing issues in the wild, you can ask them to specifically enable "Troubleshooting Mode" in the Verifier UI. This displays a debug overlay and captures additional diagnostics. |
🧰 Tools
🪛 LanguageTool
[grammar] ~106-~106: Ensure spelling is correct
Context: ...issues in the wild, you can ask them to specificually enable "Troubleshooting Mode" in the Ve...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
In `@content/docs/troubleshooting/index.mdx` at line 106, Fix the typo in the
documentation sentence that contains "Troubleshooting Mode" by replacing
"specificually" with "specifically" so the line reads: 'If a user is facing
issues in the wild, you can ask them to specifically enable "Troubleshooting
Mode" in the Verifier UI.' Locate the sentence with "Troubleshooting Mode" and
correct the misspelling.
|
|
||
| If a user is facing issues in the wild, you can ask them to specificually enable "Troubleshooting Mode" in the Verifier UI. This displays a debug overlay and captures additional diagnostics. | ||
|
|
||
| [**How to Enable Troubleshooting Mode →**](./troubleshooting/enable-troubleshooting-mode) |
There was a problem hiding this comment.
Broken relative link.
📝 Proposed fix
-[**How to Enable Troubleshooting Mode →**](./troubleshooting/enable-troubleshooting-mode)
+[**How to Enable Troubleshooting Mode →**](./enable-troubleshooting-mode)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| [**How to Enable Troubleshooting Mode →**](./troubleshooting/enable-troubleshooting-mode) | |
| [**How to Enable Troubleshooting Mode →**](./enable-troubleshooting-mode) |
🤖 Prompt for AI Agents
In `@content/docs/troubleshooting/index.mdx` at line 108, Link "[**How to Enable
Troubleshooting Mode →**](./troubleshooting/enable-troubleshooting-mode)" is
broken; update that reference to the actual existing doc path (for example add
the extension or correct relative depth — e.g.,
"./troubleshooting/enable-troubleshooting-mode.mdx" or
"../troubleshooting/enable-troubleshooting-mode" depending on where the target
file lives) so it resolves correctly, then verify by running the docs build or
preview to ensure the link points to the intended page.
|
|
||
| If you are seeing generic failures, check our guide on common environmental issues like network stability, memory constraints, or outdated OS versions. | ||
|
|
||
| [**View Potential Failure Reasons →**](./troubleshooting/potential-failure-reasons) |
There was a problem hiding this comment.
Broken relative link.
📝 Proposed fix
-[**View Potential Failure Reasons →**](./troubleshooting/potential-failure-reasons)
+[**View Potential Failure-reasons →**](./potential-failure-reasons)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| [**View Potential Failure Reasons →**](./troubleshooting/potential-failure-reasons) | |
| [**View Potential Failure-reasons →**](./potential-failure-reasons) |
🤖 Prompt for AI Agents
In `@content/docs/troubleshooting/index.mdx` at line 118, The relative link target
"./troubleshooting/potential-failure-reasons" in the link "[**View Potential
Failure Reasons →**]" is broken; update the href to the correct path (for
example add the file extension or adjust the relative path to match the actual
file location, e.g. "./troubleshooting/potential-failure-reasons.mdx" or
"../troubleshooting/potential-failure-reasons") and verify the target file
exists so the link resolves correctly.
|
|
||
| A stable and reasonably fast internet connection is essential. If your network is slow, drops frequently, or is unreliable, the communication with our servers can be interrupted, causing the process to fail. | ||
|
|
||
| ### Outdated Operating System 낡 |
There was a problem hiding this comment.
Unexpected character in heading.
The heading contains a Korean character "낡" which appears unintentional. This should likely be an emoji or removed entirely.
📝 Proposed fix
-### Outdated Operating System 낡
+### Outdated Operating System 📱📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Outdated Operating System 낡 | |
| ### Outdated Operating System 📱 |
🤖 Prompt for AI Agents
In `@content/docs/troubleshooting/potential-failure-reasons.mdx` at line 26, The
heading "### Outdated Operating System 낡" contains an unintended Korean
character "낡"; remove that character or replace it with the intended emoji (or
nothing) so the heading reads cleanly (e.g., "### Outdated Operating System" or
"### Outdated Operating System ⚠️"); update the heading line in the document
(the heading text shown) accordingly.
3 participants
Description
Testing (ignore for documentation update)
Type of change
Checklist:
Additional Notes:
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.