Skip to content

docs(code-push): add runtime error reference page#586

Closed
eseidel wants to merge 2 commits into
mainfrom
docs/runtime-error-reference
Closed

docs(code-push): add runtime error reference page#586
eseidel wants to merge 2 commits into
mainfrom
docs/runtime-error-reference

Conversation

@eseidel

@eseidel eseidel commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

What

Adds a new page to the Code Push docs: Error Reference (code-push/runtime-errors.mdx), explaining the runtime errors and exceptions most commonly reported by apps that use the optional shorebird_code_push package.

This is the first reference-style page in the docs and the first page focused on the package's runtime behavior (the API itself remains documented on pub.dev).

Framing

Written as operational documentation, not an API reference:

  • The shorebird_code_push package is called out as optional (Shorebird patches automatically without it).
  • Notes that Shorebird has no built-in crash/error reporting — you only see these errors if you've wired up your own (links to the existing Sentry/Crashlytics pages).
  • Full API signatures are deferred to pub.dev; this page only helps interpret errors.
  • Lives entirely under code-push/ (no new top-level section).

Contents

  • How to read an UpdateException (<message> / <reason>), with a table of UpdateFailureReason values.
  • Errors grouped by class: benign (noUpdate, Update already in progress), network/transient, device/environment, and patch-state.
  • noUpdate guidance: it's obsolete — upgrade shorebird_code_push to 2.0.6+.
  • Cross-linked from the Troubleshooting page.

Verification

npm run build (astro check + build) passes with 0 errors / 0 warnings, and the internal-link validator reports all links valid.

eseidel added 2 commits July 2, 2026 15:56
Adds an operational reference for the runtime errors surfaced by the
optional shorebird_code_push package, explaining what each error/exception
means and what to do about it. Frames the content as ops documentation
(you only see these via your own error reporting; Shorebird has no built-in
crash reporting) and defers full API signatures to pub.dev.

Cross-links the new page from the Troubleshooting page.
@eseidel

eseidel commented Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

Closing in favor of fixing the root cause: the four-value UpdateFailureReason enum collapses most real failures (network, permissions, disk-full, server) into unknown, and this doc only existed to help humans do the classification the enum should do. We're going to plumb richer, categorized failure reasons through the Rust updater and the shorebird_code_push Dart layer instead. May revisit a slimmed-down docs page afterward.

@eseidel eseidel closed this Jul 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant