TypeError: Cannot read property 'OS' of undefined in Libraries/Settings/Settings.js due to circular dependency on startup

[Capstan]

Description

When launching React Native applications with specific initialization/module loading sequences (such as during the boot of Expo host apps), the app crashes on startup with the following error:

[runtime not ready]: TypeError: Cannot read property 'OS' of undefined

Steps to reproduce

A minimal reproduction repository is available at Capstan/reproducer-react-native-settings on branch repro/settings-circular-dependency.

You can clone it, checkout the branch, and run:

yarn install
yarn test

Alternatively, you can minimally reproduce this crash by placing the following Jest unit test inside packages/react-native/Libraries/Settings/__tests__/Settings-test.js and running it:

/**
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 *
 * @flow strict-local
 * @format
 * @oncall react_native
 */

'use strict';

describe('Settings', () => {
  beforeEach(() => {
    jest.resetModules();
  });

  it('should not throw due to circular dependency during Platform initialization', () => {
    // Intercept NativePlatformConstantsIOS (which Platform.ios requires during load)
    // to simulate another module requiring Settings during Platform's initialization phase.
    jest.mock('../../Utilities/NativePlatformConstantsIOS', () => {
      // Accessing Settings while Platform is loading
      require('../Settings.js');
      return {
        getConstants() {
          return {
            interfaceIdiom: 'phone',
            isTesting: true,
            osVersion: '16.0',
            systemName: 'iOS',
          };
        },
      };
    });

    expect(() => {
      require('../../Utilities/Platform');
    }).not.toThrow();
  });
});

React Native Version

0.85.3

Affected Platforms

Runtime - Android, Runtime - iOS

Output of npx @react-native-community/cli info

System:
  OS: macOS 26.5
  CPU: (10) arm64 Apple M1 Max
  Memory: 2.55 GB / 64.00 GB
  Shell:
    version: "5.9"
    path: /bin/zsh
Binaries:
  Node:
    version: 26.0.0
    path: /opt/homebrew/bin/node
  Yarn: Not Found
  npm:
    version: 11.12.1
    path: /opt/homebrew/bin/npm
  Watchman: Not Found
Managers:
  CocoaPods:
    version: 1.16.2
    path: /opt/homebrew/lib/ruby/gems/4.0.0/bin/pod
SDKs:
  iOS SDK:
    Platforms:
      - DriverKit 25.5
      - iOS 26.5
      - macOS 26.5
      - tvOS 26.5
      - visionOS 26.5
      - watchOS 26.5
  Android SDK:
    API Levels:
      - "36"
      - "36"
    Build Tools:
      - 35.0.0
      - 36.0.0
      - 36.1.0
      - 37.0.0
    System Images:
      - android-34 | Google APIs ARM 64 v8a
      - android-35 | Google Play ARM 64 v8a
    Android NDK: Not Found
IDEs:
  Android Studio: 2025.3 AI-253.32098.37.2534.15336583
  Xcode:
    version: 26.5/17F42
    path: /usr/bin/xcodebuild
Languages:
  Java:
    version: 26.0.1
    path: /opt/homebrew/opt/openjdk/bin/javac
  Ruby:
    version: 4.0.5
    path: /opt/homebrew/opt/ruby/bin/ruby

Stacktrace or Logs

Error name:    "TypeError"
Error message: "Cannot read properties of undefined (reading 'OS')"

  at Object.OS (node_modules/react-native/Libraries/Settings/Settings.js:21:14)
  at require (__tests__/SettingsCircularDependency.test.ts:17:7)
  at Object.require (node_modules/react-native/Libraries/Utilities/Platform.ios.js:13:1)

MANDATORY Reproducer

https://github.com/Capstan/reproducer-react-native-settings/tree/repro/settings-circular-dependency

Screenshots and Videos

No response

[Capstan]

Reference Issue:

• Expo issue reference: bare-expo app startup crash on iOS and Android: TypeError: Cannot read property 'OS' of undefined expo/expo#46264

---

Affected React Native Versions:

• First affected version: 0.80.0 (introduced via commit 1bb929b / PR Add explicit compatibility for platform specific files under "exports" #50426, merged on April 3, 2025)
• Verified affected versions: 0.80.0 through 0.85.3 (latest stable), as well as 0.86.0 release candidates.

---

Root Cause:

In React Native v0.80.0+, a compatibility wrapper file was added at Libraries/Settings/Settings.js. This file statically imports Platform and immediately attempts to access Platform.OS at module load-time:

import Platform from '../Utilities/Platform';

let Settings: {
  get(key: string): any,
  set(settings: Object): void,
  watchKeys(keys: string | Array<string>, callback: () => void): number,
  clearWatch(watchId: number): void,
  ...
};

if (Platform.OS === 'ios') {
  Settings = require('./Settings').default;
} else {
  Settings = require('./SettingsFallback').default;
}

export default Settings;

If Settings.js is required during the initialization of Platform.js (creating a circular require graph), require('../Utilities/Platform') returns undefined (or an empty module export object), resulting in a fatal TypeError when accessing Platform.OS.

[Capstan]

Proposed Fix (Lazy Loading):

To prevent this load-time crash, we can avoid checking Platform.OS when Settings.js is first imported. Instead, we can export a wrapper object that resolves and delegates to the underlying implementation only when one of the APIs is first invoked:

let cachedSettings = null;

function getSettings() {
  if (cachedSettings == null) {
    if (Platform.OS === 'ios') {
      cachedSettings = require('./Settings').default;
    } else {
      cachedSettings = require('./SettingsFallback').default;
    }
  }
  return cachedSettings;
}

const Settings = {
  get: (key) => getSettings().get(key),
  set: (settings) => getSettings().set(settings),
  watchKeys: (keys, callback) => getSettings().watchKeys(keys, callback),
  clearWatch: (watchId) => getSettings().clearWatch(watchId),
};

export default Settings;

This breaks the circular load-time dependency by deferring the Platform.OS check until runtime API usage.

[Capstan]

⚠️ Update: Initial lazy-loading fix is insufficient

After further testing in an Expo integration environment, the proposed lazy-loading change (which defers the platform check to runtime but keeps the top-level Platform import) is not sufficient to resolve the startup crash.

Because Platform is still imported at the top level of Settings.js:

1. In a circular dependency loop, the bundler (Metro) resolves the top-level Platform import early, which returns an incomplete/empty exports object ({}).
2. The top-level Platform identifier in Settings.js remains permanently bound to this empty/incomplete object.
3. When Platform.OS is evaluated at runtime inside the lazy getter, it still crashes (e.g. TypeError: Cannot read property 'OS' of undefined or similar property access error) because the bound Platform reference is empty.

So the top-level Platform identifier binding problem happens anyway. Still investigating if there's a more robust way to solve this.