1 files changed, 42 insertions, 0 deletions
diff --git a/docs/guide/upgrading.md b/docs/guide/upgrading.md
index 4a5a2ea9..0572f5f1 100644
--- a/docs/guide/upgrading.md
+++ b/docs/guide/upgrading.md
@@ -97,6 +97,48 @@ for (let user of users) {
 
 For more information refer to our [Localization Guide](localization).
 
+### For missing locale data, Faker will now throw instead of returning `undefined` or `a`-`c`
+
+::: note Note
+The following section mostly applies to custom-built Faker instances.
+:::
+
+Previously, for example if `en` didn't have data for `animal.cat`, then `faker.animal.cat()` would have returned one of `a`, `b` or `c` (`arrayElement`'s default value).
+These values aren't expected/useful as a fallback and potentially also violate the method's defined return type definitions (in case it doesn't return a `string`).
+
+We have now addressed this by changing the implementation so that an error is thrown, prompting you to provide/contribute the missing data.
+This will also give you detailed information which data are missing.
+If you want to check for data you can either use `entry in faker.definitions.category` or use `faker.rawDefinitions.category?.entry` instead.
+
+```ts
+import { Faker, fakerES, es } from '@faker-js/faker';
+
+const fakerES_noFallbacks = new Faker({
+  locale: [es],
+});
+fakerES.music.songName(); // 'I Want to Hold Your Hand' (fallback from en)
+// Previously:
+//fakerES_noFallbacks.music.songName(); // 'b'
+// Now:
+fakerES_noFallbacks.music.songName(); // throws a FakerError
+```
+
+This also has an impact on data that aren't applicable to a locale, for example Chinese doesn't use prefixes in names.
+
+```ts
+import { faker, fakerZH_CN, zh_CN } from '@faker-js/faker';
+
+const fakerZH_CN_noFallbacks = new Faker({
+  locale: [zh_CN],
+});
+
+faker.name.prefix(); // 'Mr'
+// Previously:
+//fakerZH_CN_noFallbacks.person.prefix(); // undefined
+// Now:
+fakerZH_CN.person.prefix(); // throws a FakerError
+```
+
 ### `faker.mersenne` and `faker.helpers.repeatString` removed
 
 `faker.mersenne` and `faker.helpers.repeatString` were only ever intended for internal use, and are no longer available.