Implement solution to replace error messages with error codes, instead of removing error messages. #8313

MarkDuckworth · 2024-06-12T17:42:42Z

In the Firestore SDK, error messages are removed from fail(message) and hardAssert(condition, message) statements during the build. Removal of error messages is performed to reduce bundle size, however this comes at a cost to usability. Specifically, this means that production error messages can be unhelpful.

Here's an example of a production error message today (without this change):

FIRESTORE (1.2.3) INTERNAL ASSERTION FAILED: Unexpected state

"Unexpected state" is the same reason given for 140+ error conditions after the detailed error messages have been stripped.

To improve debuggability of error messages, this PR adds a numeric error code to each fail and hardAssert statement. These numeric error codes are unique and will not be removed from the build output. The full error message will still be removed during the build, but the resulting error messages with this change will give customers and support more information to debug the output.

Heres and example of a production error message after this change is applied:

FIRESTORE (1.2.3) INTERNAL ASSERTION FAILED: Unexpected state (code: e2301882) CONTEXT: {"example": "relevant JSON serialized state of the application when the assertion failed."}

Note: A quick command to help search for duplicate error codes is:
find . -type f -name '*.ts' -exec grep -E -i -h -o '0x[0-9a-f]{4,10}' {} + | sort | uniq -c | sort

…d of removing error messages.

changeset-bot · 2024-06-12T17:42:47Z

🦋 Changeset detected

Latest commit: 1733442

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@firebase/firestore	Patch
firebase	Patch
@firebase/firestore-compat	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2024-06-12T17:44:46Z

Changeset File Check ✅

No modified packages are missing from the changeset file.
No changeset formatting errors detected.

google-oss-bot · 2024-06-12T19:22:51Z

Size Report ¹

Affected Products

@firebase/firestore
Type Base (933ba9d) Merge (68781de) Diff
browser 382 kB 384 kB +2.05 kB (+0.5%)
main 591 kB 594 kB +2.82 kB (+0.5%)
module 382 kB 384 kB +2.05 kB (+0.5%)
react-native 382 kB 384 kB +2.05 kB (+0.5%)
@firebase/firestore-lite
Type Base (933ba9d) Merge (68781de) Diff
browser 113 kB 114 kB +827 B (+0.7%)
main 155 kB 157 kB +1.26 kB (+0.8%)
module 113 kB 114 kB +827 B (+0.7%)
react-native 113 kB 114 kB +827 B (+0.7%)

`bundle`

15 size changes

Type	Base (`933ba9d`)	Merge (`68781de`)	Diff
firestore (CSI Auto Indexing Disable and Delete)	272 kB	274 kB	+1.61 kB (+0.6%)
firestore (CSI Auto Indexing Enable)	272 kB	274 kB	+1.61 kB (+0.6%)
firestore (Persistence)	304 kB	305 kB	+1.80 kB (+0.6%)
firestore (Query Cursors)	250 kB	251 kB	+1.06 kB (+0.4%)
firestore (Query)	248 kB	249 kB	+1.06 kB (+0.4%)
firestore (Read data once)	236 kB	237 kB	+1.04 kB (+0.4%)
firestore (Read Write w Persistence)	328 kB	330 kB	+1.84 kB (+0.6%)
firestore (Realtime updates)	238 kB	239 kB	+1.05 kB (+0.4%)
firestore (Transaction)	215 kB	216 kB	+1.01 kB (+0.5%)
firestore (Write data)	214 kB	215 kB	+972 B (+0.5%)
firestore-lite (Query Cursors)	104 kB	104 kB	+587 B (+0.6%)
firestore-lite (Query)	99.9 kB	100 kB	+587 B (+0.6%)
firestore-lite (Read data once)	75.4 kB	75.9 kB	+497 B (+0.7%)
firestore-lite (Transaction)	101 kB	101 kB	+692 B (+0.7%)
firestore-lite (Write data)	85.0 kB	85.5 kB	+517 B (+0.6%)

`firebase`

Type	Base (`933ba9d`)	Merge (`68781de`)	Diff
firebase-compat.js	794 kB	796 kB	+2.00 kB (+0.3%)
firebase-firestore-compat.js	340 kB	342 kB	+2.01 kB (+0.6%)
firebase-firestore-lite.js	131 kB	132 kB	+827 B (+0.6%)
firebase-firestore.js	440 kB	442 kB	+1.99 kB (+0.5%)

Test Logs

https://storage.googleapis.com/firebase-sdk-metric-reports/wJ3FMmmOxy.html

dconeybe · 2024-06-12T19:25:47Z

IMO adding 2.4 kB to the bundle size is questionable if it's worth it.

google-oss-bot · 2024-06-12T19:35:19Z

Size Analysis Report ¹

This report is too large (720,496 characters) to be displayed here in a GitHub comment. Please use the below link to see the full report on Google Cloud Storage.

Test Logs

https://storage.googleapis.com/firebase-sdk-metric-reports/yAzJjxEcec.html

MarkDuckworth · 2024-06-12T19:35:49Z

IMO adding 2.4 kB to the bundle size is questionable if it's worth it.

@dconeybe, in your opinion, what increase in bundle size would be acceptable?

It's <=1% increase, which seems like a reasonable tradeoff for making production issues more debuggable. But I'm seeing if I can make the impact smaller.

dconeybe · 2024-06-12T20:34:09Z

IMO adding 2.4 kB to the bundle size is questionable if it's worth it.

@dconeybe, in your opinion, what increase in bundle size would be acceptable?

It's <=1% increase, which seems like a reasonable tradeoff for making production issues more debuggable. But I'm seeing if I can make the impact smaller.

I'd hope it would be less than 1kB. But this is just one man's opinion. Please don't take it as gospel truth.

…maller.

…uckworth/error-codes

dconeybe

This is fantastic! I especially like how you added the "context" which will be incredibly useful when debugging. Thanks for doing this, Mark.

dconeybe · 2025-04-02T12:37:35Z

Please let the team know about the 1% increase in code bundle size and make sure they're ok with it. The "firestore (Read Write w Persistence)" bundle increased by 2.77 kB which is probably worth it, but I'd make sure the team knows.

Also, please add a change set with a minor version bump and a change log entry.

github-actions · 2025-04-02T18:30:29Z

Vertex AI Mock Responses Check ⚠️

A newer major version of the mock responses for Vertex AI unit tests is available. update_vertexai_responses.sh should be updated to clone the latest version of the responses: v8.0

hsubox76

Reminder to add a changeset if you want it to publish.

… new and check

dconeybe · 2025-04-03T13:22:49Z

FWIW I much prefer the "hashes" you had before over error codes numerically incrementing from zero. The reason is that hashes have much better "SEO" because of their uniqueness. Firstly, the improved SEO allows customers to search for the error code and find relevant bug reports, stack overflow posts, etc. If they search for error code "3" they won't likely get anything useful, but if they search for "jszxcbe37k" they'll likely get results that relate directly to the error that they are experiencing. Likewise, when we as Firestore SDK developers get a bug report with error code "3" it's much more difficult to find its place in the source code than searching for "jszxcbe37k".

For Data Connect I chose this alphabet: [23456789abcdefghjkmnopqrstuvwxyz](https://github.com/firebase/firebase-android-sdk/blob/a0a02a73f67f6447c739d920f614c8bd5331c591/firebase-dataconnect/src/main/kotlin/com/google/firebase/dataconnect/util/AlphanumericStringUtil.kt#L31C45-L31C79) (a length of 32). This alphabet is most of the English lowercase letters and most digits, with those that "look alike" removed (e.g. zero "0" and lowercase-o "o"). This leads to incredibly unique 6-digit strings.

Implement solution to replace error messages with error codes, instea…

53603f3

…d of removing error messages.

MarkDuckworth requested review from a team as code owners June 12, 2024 17:42

Try-catch on saveErrorCode

c7c099a

Replace string errorCodes with numeric errorIds to make the bundles s…

39cf218

…maller.

MarkDuckworth mentioned this pull request Jun 20, 2024

FIRESTORE (10.12.0) INTERNAL ASSERTION FAILED: Unexpected state #8250

Open

MarkDuckworth added 2 commits April 1, 2025 13:40

Merge branch 'main' of github.com:firebase/firebase-js-sdk into markd…

d441861

…uckworth/error-codes

Added fixed error code values to source

448257f

MarkDuckworth assigned dconeybe Apr 1, 2025

dconeybe approved these changes Apr 2, 2025

View reviewed changes

MarkDuckworth added 2 commits April 2, 2025 12:27

Removed 4 characters from each error code

70dcaa7

Deduplicated an error code

a86219b

MarkDuckworth assigned hsubox76 Apr 2, 2025

Fix tests

8b7c3f2

hsubox76 reviewed Apr 2, 2025

View reviewed changes

MarkDuckworth added 2 commits April 2, 2025 18:25

Error codes numerically increasing starting at 0 with tools to create…

26cdf17

… new and check

Instructions for using error-code-tool

8e28999

Create odd-wolves-sit.md

1733442

MarkDuckworth requested a review from a team as a code owner April 3, 2025 13:23

hsubox76 approved these changes Apr 3, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement solution to replace error messages with error codes, instead of removing error messages. #8313

Implement solution to replace error messages with error codes, instead of removing error messages. #8313

MarkDuckworth commented Jun 12, 2024 •

edited

Loading

changeset-bot bot commented Jun 12, 2024 •

edited

Loading

github-actions bot commented Jun 12, 2024 •

edited

Loading

google-oss-bot commented Jun 12, 2024 •

edited

Loading

`@firebase/firestore`

`@firebase/firestore-lite`

`bundle`

`firebase`

dconeybe commented Jun 12, 2024

google-oss-bot commented Jun 12, 2024 •

edited

Loading

MarkDuckworth commented Jun 12, 2024 •

edited

Loading

dconeybe commented Jun 12, 2024

dconeybe left a comment

dconeybe commented Apr 2, 2025

github-actions bot commented Apr 2, 2025

hsubox76 left a comment

dconeybe commented Apr 3, 2025

Implement solution to replace error messages with error codes, instead of removing error messages. #8313

Are you sure you want to change the base?

Implement solution to replace error messages with error codes, instead of removing error messages. #8313

Conversation

MarkDuckworth commented Jun 12, 2024 • edited Loading

changeset-bot bot commented Jun 12, 2024 • edited Loading

🦋 Changeset detected

github-actions bot commented Jun 12, 2024 • edited Loading

Changeset File Check ✅

google-oss-bot commented Jun 12, 2024 • edited Loading

Size Report 1

Affected Products

@firebase/firestore

@firebase/firestore-lite

bundle

firebase

Test Logs

dconeybe commented Jun 12, 2024

google-oss-bot commented Jun 12, 2024 • edited Loading

Size Analysis Report 1

Test Logs

MarkDuckworth commented Jun 12, 2024 • edited Loading

dconeybe commented Jun 12, 2024

dconeybe left a comment

Choose a reason for hiding this comment

dconeybe commented Apr 2, 2025

github-actions bot commented Apr 2, 2025

Vertex AI Mock Responses Check ⚠️

hsubox76 left a comment

Choose a reason for hiding this comment

dconeybe commented Apr 3, 2025

MarkDuckworth commented Jun 12, 2024 •

edited

Loading

changeset-bot bot commented Jun 12, 2024 •

edited

Loading

github-actions bot commented Jun 12, 2024 •

edited

Loading

google-oss-bot commented Jun 12, 2024 •

edited

Loading

Size Report ¹

`@firebase/firestore`

`@firebase/firestore-lite`

`bundle`

`firebase`

google-oss-bot commented Jun 12, 2024 •

edited

Loading

Size Analysis Report ¹

MarkDuckworth commented Jun 12, 2024 •

edited

Loading