docs: add common Capgo update failure troubleshooting guide#488
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a6cdb4df82
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughAdds a new dedicated documentation page for common live-update failure codes, inserts cross-references to that page in two existing troubleshooting docs (one inserted twice in troubleshooting.mdx), and adds a 301 redirect plus a sidebar nav entry in the Astro config for the new page. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 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)
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.
🧹 Nitpick comments (2)
src/content/docs/docs/getting-started/common-update-problems.mdx (2)
1-6: Consider addingprev: false/next: falsefor consistency with sibling pages.Both
troubleshooting.mdx(order 6) andwrapping-up.mdx(order 8) suppress footer navigation withprev: false/next: false. Without these on this page, Starlight will auto-render "previous: Troubleshooting" and "next: Wrapping up" footer arrows here — while those neighboring pages won't show a corresponding arrow back. Starlight defines whether the footer includes previous and next page links, and a page can override this setting using theprevandnextfrontmatter fields. This creates asymmetric navigation unless intentional.✏️ Proposed fix
--- title: Common Update Problems description: Understand common Capgo live-update failure codes, what causes them, and how to fix them quickly. sidebar: order: 7 +prev: false +next: false ---🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/docs/getting-started/common-update-problems.mdx` around lines 1 - 6, Add explicit frontmatter fields prev: false and next: false to the "Common Update Problems" page's frontmatter (the YAML block at the top of src/content/docs/docs/getting-started/common-update-problems.mdx) so the page suppresses Starlight footer navigation like its siblings; update the existing frontmatter (alongside title and order) to include prev: false and next: false to ensure consistent navigation behavior with troubleshooting.mdx and wrapping-up.mdx.
182-185: Vary sentence openers in the diagnostic checklist to improve readability.Items 2, 3, and 4 all begin with "Confirm", which static analysis flags as repetitive. A simple rewording improves scannability.
✏️ Suggested rewording
-2. Confirm `CapacitorUpdater.version` matches installed native app version. -3. Confirm channel policy (`disable_auto_update`) matches intended rollout. -4. Confirm platform/build target toggles allow this device. +2. Verify `CapacitorUpdater.version` matches installed native app version. +3. Check that channel policy (`disable_auto_update`) matches intended rollout. +4. Ensure platform/build target toggles allow this device.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/docs/getting-started/common-update-problems.mdx` around lines 182 - 185, Reword the repetitive checklist items so they don't all start with "Confirm": keep item 1 as-is, change item 2 referencing CapacitorUpdater.version to something like "Verify that CapacitorUpdater.version matches the installed native app version", rephrase item 3 about channel policy/disable_auto_update to "Ensure the channel policy (disable_auto_update) matches the intended rollout", and reword item 4 about platform/build target toggles to "Check that platform/build target toggles allow this device" so the list reads more varied and scannable.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@src/content/docs/docs/getting-started/common-update-problems.mdx`:
- Around line 1-6: Add explicit frontmatter fields prev: false and next: false
to the "Common Update Problems" page's frontmatter (the YAML block at the top of
src/content/docs/docs/getting-started/common-update-problems.mdx) so the page
suppresses Starlight footer navigation like its siblings; update the existing
frontmatter (alongside title and order) to include prev: false and next: false
to ensure consistent navigation behavior with troubleshooting.mdx and
wrapping-up.mdx.
- Around line 182-185: Reword the repetitive checklist items so they don't all
start with "Confirm": keep item 1 as-is, change item 2 referencing
CapacitorUpdater.version to something like "Verify that CapacitorUpdater.version
matches the installed native app version", rephrase item 3 about channel
policy/disable_auto_update to "Ensure the channel policy (disable_auto_update)
matches the intended rollout", and reword item 4 about platform/build target
toggles to "Check that platform/build target toggles allow this device" so the
list reads more varied and scannable.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
src/content/docs/docs/getting-started/common-update-problems.mdxsrc/content/docs/docs/getting-started/troubleshooting.mdxsrc/content/docs/docs/getting-started/wrapping-up.mdx
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
src/content/docs/docs/plugins/updater/commonProblems.mdx (1)
180-186: Nit: repetitive sentence starts in the checklist.All five items start with "Confirm". Consider varying the lead-in for a couple of items (e.g., "Verify", "Check", "Ensure") to improve readability, though this is purely stylistic for a numbered checklist.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/docs/plugins/updater/commonProblems.mdx` around lines 180 - 186, Update the "Quick diagnostic checklist" to avoid repeating the word "Confirm" by varying the lead-in verbs for some items: keep the checklist titled "Quick diagnostic checklist" and replace two or three of the repeated "Confirm" starters (for example the lines referencing "CapacitorUpdater.version", "channel policy (`disable_auto_update`)", or the "platform/build target toggles") with alternatives like "Verify", "Check", or "Ensure" to improve readability while preserving the original checklist meaning and order.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@astro.config.mjs`:
- Around line 106-109: Replace internal links that point to the redirected path
with the canonical lowercase path: update occurrences of
"/docs/plugins/updater/commonProblems/" in troubleshooting.mdx and debugging.mdx
to "/docs/plugins/updater/commonproblems/"; then add an explicit sidebar entry
to the Updater section's manual items array (where the Updater sidebar is
defined) by inserting an item with label "Common Update Problems" and link
"/docs/plugins/updater/commonproblems" so the new page appears in navigation
(this complements the existing 301 redirect mapping in astro.config.mjs).
In `@src/content/docs/docs/getting-started/troubleshooting.mdx`:
- Around line 143-149: The link under the "Common update failure codes" section
uses camelCase path `/docs/plugins/updater/commonProblems/` which triggers a
redirect; update the href to the canonical lowercase path
`/docs/plugins/updater/commonproblems/` so the link points directly to the new
dedicated guide (replace the literal `/docs/plugins/updater/commonProblems/`
with `/docs/plugins/updater/commonproblems/` in the markdown).
In `@src/content/docs/docs/plugins/updater/commonProblems.mdx`:
- Around line 1-6: The frontmatter setting sidebar.order: 7 has no effect
because the Updater sidebar section is configured with a manual items array in
astro.config.mjs; either add an explicit entry for this page into the Updater
section’s items array (so the page appears in the sidebar), or change the
Updater sidebar section to use autogenerate so frontmatter order is
respected—locate the Updater sidebar config (the items array referenced in
astro.config.mjs) and either insert a new item pointing to this
docs/plugins/updater/commonProblems.mdx or switch that section to autogenerate
and keep the frontmatter order.
---
Nitpick comments:
In `@src/content/docs/docs/plugins/updater/commonProblems.mdx`:
- Around line 180-186: Update the "Quick diagnostic checklist" to avoid
repeating the word "Confirm" by varying the lead-in verbs for some items: keep
the checklist titled "Quick diagnostic checklist" and replace two or three of
the repeated "Confirm" starters (for example the lines referencing
"CapacitorUpdater.version", "channel policy (`disable_auto_update`)", or the
"platform/build target toggles") with alternatives like "Verify", "Check", or
"Ensure" to improve readability while preserving the original checklist meaning
and order.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
astro.config.mjssrc/content/docs/docs/getting-started/troubleshooting.mdxsrc/content/docs/docs/plugins/updater/commonProblems.mdxsrc/content/docs/docs/plugins/updater/debugging.mdx
✅ Files skipped from review due to trivial changes (1)
- src/content/docs/docs/plugins/updater/debugging.mdx
|
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/content/docs/docs/getting-started/troubleshooting.mdx`:
- Around line 143-149: The docs reference backend error codes inconsistently;
update the references so both files use the canonical snake_case used in
commonProblems.mdx: replace/augment the camelCase entries in debugging.mdx
(e.g., disableAutoUpdateToMajor, cannotUpdateViaPrivateChannel) with their
snake_case equivalents (disable_auto_update_to_major,
cannot_update_via_private_channel), and add semver_error to the backend codes
table in debugging.mdx so it matches troubleshooting.mdx and commonProblems.mdx;
ensure troubleshooting.mdx continues to reference disable_auto_update_to_major,
semver_error, cannot_update_via_private_channel (or add parenthetical camelCase
variants if you prefer showing both formats).
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
astro.config.mjssrc/content/docs/docs/getting-started/troubleshooting.mdxsrc/content/docs/docs/plugins/updater/debugging.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- astro.config.mjs
- Refactor explainCommonUpdateError() to use data-driven errorHints map referencing the new Common Update Problems docs page from Cap-go/website#488, reducing code duplication from 13.4% to well under the 3% SonarQube threshold - Extract shared extractExtra() helper to eliminate repeated JSON-extra logic - Make pollUpdateAvailability() resilient to transient 5xx/network errors by retrying within the 60s poll window instead of failing immediately (P2) - Reload capacitor config before step 12 probe to avoid stale app_id/version values after earlier onboarding steps mutate the config (P1) - Persist selected platform in onboarding temp file so resumed sessions at step 12 use the correct platform instead of defaulting to ios (P2)
Add documentation for the on_premise_app error that the backend returns when an app_id doesn't exist in Capgo, the app is flagged as on-premise, or the org plan is cancelled.
|
2 participants
Summary (AI generated)
getting-started/common-update-problemscovering common update refusal/failure codes from/updatesWrapping upafter the new troubleshooting guideMotivation (AI generated)
Users hitting update refusal codes (for example
disable_auto_update_to_major) need a single, practical reference that explains what each error means and what to change to fix it.Business Impact (AI generated)
This should reduce onboarding friction and support load by turning opaque backend errors into clear remediation steps.
Test Plan (AI generated)
bun run build(blocked in this environment:buncommand not available)Generated with AI
Summary by CodeRabbit