[Due for payment 2025-09-04] [$250] [Onyx] Fix infinite loading issue for empty collections in useOnyx

[kacper-mikolajczak]

Problem

The useOnyx hook is experiencing an infinite loading state when subscribing to collection keys that don't exist in storage.

Solution

Remove conditional check from subscribeToKey that prevents collections to be treated equally as other keys in terms of empty state identification (nullishStorageKeys). (source)

Draft PR

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~021954839604653186908
• Upwork Job ID: 1954839604653186908
• Last Price Increase: 2025-08-11

Issue Owner

Current Issue Owner: @Christinadobrzyn

[kacper-mikolajczak]

Explanation

The problem stemmed from the subscribeToKey function in OnyxUtils.ts. When a connection is made to a key that doesn't exist in storage (returns no matching keys), the system was supposed to:

1. Add the key to the nullish storage keys set via cache.addNullishStorageKey(mapping.key)
2. Send a null value to the connection to indicate no data exists
3. Allow useOnyx to transition from loading to loaded state

However, the original code had a conditional check that prevented collection keys from being added to the nullish storage keys set:

if (matchingKeys.length === 0) {
    if (mapping.key && !isCollectionKey(mapping.key)) {  // ❌ This condition excluded collections
        cache.addNullishStorageKey(mapping.key);
    }
    // ...
}

The useOnyx hook determines fetchStatus based on several factors, including whether there's cache available for a key:

const hasCacheForKey = OnyxCache.hasCacheForKey(key);

The hasCacheForKey method returns true if either:

• The key has actual cached data, OR
• The key is in the nullish storage keys set

hasCacheForKey(key: OnyxKey): boolean {
    return this.storageMap[key] !== undefined || this.hasNullishStorageKey(key);
}

1. When useOnyx subscribes to a non-existent collection key
2. subscribeToKey finds no matching keys (matchingKeys.length === 0)
3. Due to the conditional check, collection keys were NOT added to nullish storage keys
4. hasCacheForKey returns false for the collection key
5. useOnyx.getSnapshot() continues to return loading status indefinitely
6. The hook never transitions to loaded state, causing infinite loading

This fix resolves a critical UX issue where useOnyx would get stuck in an infinite loading state for non-existent collections. The solution is minimal, consistent, and aligns the behavior of collection keys with individual keys. The change ensures that all Onyx keys, regardless of type, can properly transition through the loading lifecycle, providing a better developer experience and preventing UI freezes in applications using collection subscriptions.

Now tests that were added to monitor this regression (source) are passing just fine.

[fabioh8010]

cc @mountiny

[melvin-bot]

Triggered auto assignment to @Christinadobrzyn (Bug), see https://stackoverflow.com/c/expensify/questions/14418 for more details. Please add this bug to a GH project, as outlined in the SO.

[kacper-mikolajczak]

Do we have an ability to re-run tests from E/App for changes in react-native-onyx in CI? I've noticed that there were couple of test suites which process was randomly terminated on my machine (dunno why) and I would like to be certain. Thanks!

[kacper-mikolajczak]

We are going to run the App tests when bumping Onyx, but that's a little bit late in the development pipeline and was wondering if we could run them earlier.

[kacper-mikolajczak]

When locally running App tests, we've got two tests failing in DateUtilsTest.ts and UnreadIndicatorsTest.tsx but Fabio said they are known to be flaky. Shall we proceed @mountiny?