Troubleshooting

Common errors and solutions when using react-native-config-ultimate.

Note: This guide applies to v0.2.0+. Versions <0.2.0 are deprecated.

Quick Fixes

Problem	Quick Fix
Config files not generated	Run `npx rncu .env`
Values undefined at runtime	Regenerate + full rebuild (hot reload won’t work)
Android empty config `{}`	Add `setBuildConfig()` in MainApplication (required on both architectures)
iOS empty config `{}`	Run `npx rncu <env-file>` and rebuild (header is generated at build time)
iOS xcconfig not found	Drag `rncu.xcconfig` into Xcode project
TypeScript errors	Regenerate with `npx rncu .env`

Build Issues
Runtime Issues
CLI Issues
Monorepo Issues
Platform-Specific Issues

Build Issues

Build fails with “Source env file(s) changed since the rncu CLI was last run”

Error (0.3.0+):

react-native-config-ultimate — Android build error
════════════════════════════════════════════════════════════
  Source env file(s) changed since the rncu CLI was last run:
    - .env.staging changed

  Run from your React Native project root:

    npx rncu .env.staging

  Then retry the Android build.

Cause: You edited a .env file after the last npx rncu run. Gradle detects this via a SHA-256 checksum stored in rncu.yaml.sha256 and hard-fails to prevent shipping stale values.

Fix:

npx rncu .env.staging   # or whichever file the error names
./gradlew bundleRelease

When this is expected: Every time you edit .env without re-running npx rncu.

When this might be a false positive: If your editor converted line endings from LF to CRLF — see the CRLF section below.

Build fails with “requires Gradle 7.4 or newer”

Error (0.3.0+):

react-native-config-ultimate 0.3.0+ requires Gradle 7.4 or newer.
Current: 7.3.3.
Pin to react-native-config-ultimate@^0.2.0 if you cannot upgrade Gradle.

Fix — upgrade Gradle (edit android/gradle/wrapper/gradle-wrapper.properties):

distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip

Fix — pin the library if you cannot upgrade Gradle:

npm install react-native-config-ultimate@^0.2.5

See Migration Guide → 0.3.0 → Section 1 for details.

Divergence error after CRLF / line ending change

Symptom: npx rncu succeeds, but the next Android build immediately fails with a divergence error even though you didn’t change any .env values.

Cause: SHA-256 is a byte-level hash. If your editor (VS Code on Windows, Notepad, etc.) silently converted LF line endings to CRLF in the .env file, the bytes changed — even though the visible content looks identical. Gradle detects this and fails.

Fix:

Configure your editor to always use LF for .env files. In VS Code, add to .vscode/settings.json:
```
{
  "files.eol": "\n"
}
```
Or add a .editorconfig at the project root:
```
[.env*]
end_of_line = lf
```
After configuring the editor, re-run the CLI to refresh the sidecar with the correct line endings:
```
npx rncu .env   # or whichever .env file was affected
```

Why this is intentional: The hash check catches any byte-level change to ensure the CLI saw exactly the same content as what Gradle builds against. CRLF vs LF produces different binary output, which is a real content difference even if semantically equivalent.

Missing config files error

Error:

yaml file at path /X/Y/node_modules/react-native-config-ultimate/android/rncu.yaml does not exist

Or:

#error "invoke bin.js with env file before compiling native project"

Cause: The rncu CLI hasn’t been run to generate config files.

Solution: Run the CLI before building:

npx rncu .env

Prevention: Add to your build scripts:

{
  "scripts": {
    "prebuild": "rncu .env",
    "preios": "rncu .env",
    "preandroid": "rncu .env"
  }
}

CI/CD builds failing

Solution: Run rncu in your CI pipeline before the build step.

GitHub Actions:

- name: Generate env config
  run: npx rncu .env

- name: Build iOS
  run: npx react-native run-ios

AppCenter:

# appcenter-post-clone.sh
yarn install
yarn rncu .env

Bitrise / CircleCI / etc.: Same pattern — run rncu before native builds.

Runtime Issues

Android: Empty config object `{}`

Cause 1: Missing setBuildConfig call (required on both Old and New Architecture).

You will see this warning in logcat:

W/UltimateConfig: setBuildConfig was never called. Add UltimateConfigModule.setBuildConfig(BuildConfig.class) to MainApplication.onCreate() — required on both Old and New Architecture.

Solution: Add to MainApplication.kt:

import com.reactnativeultimateconfig.UltimateConfigModule

override fun onCreate() {
  super.onCreate()
  UltimateConfigModule.setBuildConfig(BuildConfig::class.java)
  // ...
}

The native module looks up your app’s generated BuildConfig class via reflection. The library cannot resolve it on its own — you have to hand it the reference once at app start, on both architectures.

Cause 2: Missing rncu.gradle in build.gradle.

Solution: Add at the top of android/app/build.gradle:

apply from: project(':react-native-config-ultimate').projectDir.getPath() + "/rncu.gradle"

Cause 3: Config wasn’t regenerated after .env changes.

Solution: Run npx rncu .env and rebuild (hot reload doesn’t work for native changes).

Values are undefined at runtime

Cause: Config files are out of sync with your .env.

Solution:

Regenerate: npx rncu .env
For native values (Info.plist, AndroidManifest): full rebuild required
For JS-only values with js_override: true: Metro reload is enough

TypeScript: Property does not exist on type

Cause: Auto-generated types are out of date.

Solution: Regenerate config (types are created alongside config):

npx rncu .env
# Types are written to node_modules/react-native-config-ultimate/lib/typescript/...

CLI Issues

“command not found” or “use strict: command not found”

Error:

/path/to/node_modules/.bin/rncu: line 1: use strict: command not found

Cause: The CLI binary is missing its shebang (#!/usr/bin/env node).

Solution:

# Reinstall the package
rm -rf node_modules
npm install

# Or if developing locally, rebuild
cd packages/react-native-config-ultimate
npm run build

CLI writes to wrong location in monorepo

Cause: rncu can’t find the correct library path.

Solution: Use --lib-root:

npx rncu --lib-root ../../node_modules/react-native-config-ultimate .env

Monorepo Issues

Android: Can’t find gradle-plugin or react-native

Error:

Included build '.../node_modules/@react-native/gradle-plugin' does not exist

Cause: Dependencies are hoisted to monorepo root, but Android expects them locally.

Solution: Create symlinks:

cd packages/your-app/node_modules
ln -sf ../../../node_modules/react-native react-native
ln -sf ../../../node_modules/@react-native @react-native

Or add to postinstall in your app’s package.json.

pnpm: Various resolution errors

Cause: pnpm’s default isolated mode is incompatible with React Native.

Solution: Add to .npmrc:

node-linker=hoisted

See Monorepo Tips for detailed pnpm setup.

rncu.yaml not found during build

Cause: The CLI wrote to the wrong node_modules location.

Solution: Specify both paths:

npx rncu \
  --project-root ./packages/my-app \
  --lib-root ./node_modules/react-native-config-ultimate \
  .env

Platform-Specific Issues

Android: “DEBUG” variable causes build error

Error:

error: incompatible types: boolean cannot be converted to String
  public static final String DEBUG = false;

Cause: DEBUG is a reserved name in Android’s BuildConfig.

Solution: Rename your variable:

- DEBUG=true
+ DEBUG_MODE=true

iOS: rncu.xcconfig not found

Error:

error: unable to open file 'ios/rncu.xcconfig'

Solution:

Generate the file:
```
npx rncu .env
```
Verify it exists:
```
ls ios/rncu.xcconfig
```
If it’s in node_modules/, you need to set up xcconfig correctly:
- Drag ios/rncu.xcconfig (from the library) into Xcode
- Set it as base configuration in Project Settings

iOS: ConfigValues.h not generated

Error:

#error "react-native-config-ultimate: ConfigValues.h not generated..."

Solution:

# Generate config
npx rncu .env

# Verify
cat node_modules/react-native-config-ultimate/ios/ConfigValues.h
# Should show your env vars, not the error message

# Rebuild
cd ios && pod install && cd ..
npx react-native run-ios

Web: Module not found

Error:

Module not found: Can't resolve 'react-native-config-ultimate'

Cause: Web bundler can’t resolve the package.

Solution: Ensure your bundler respects the browser field in package.json.

Vite: Works out of the box.

Webpack: Set resolve.mainFields:

// webpack.config.js
resolve: {
  mainFields: ['browser', 'module', 'main']
}

Metro: “Unable to resolve module”

Error:

Unable to resolve module react-native-config-ultimate

Solution: Clear Metro cache and restart:

# Clear cache and restart Metro
npx react-native start --reset-cache

# If still failing, clear node_modules
rm -rf node_modules
npm install
npx rncu .env

Architecture-Specific Issues

New Architecture: TurboModule not found

Error:

TurboModuleRegistry.getEnforcing(...): 'UltimateConfig' could not be found

Solution: Ensure pods are installed with New Arch enabled:

cd ios
RCT_NEW_ARCH_ENABLED=1 pod install
cd ..

Android: setBuildConfig not called (empty config at runtime)

Symptom: Config.MY_VAR returns undefined on Android even though BuildConfig.MY_VAR exists. The native module returns an empty object ({}).

Why: The library reads values from your app’s BuildConfig (not the library’s). It cannot resolve your app’s class automatically, so you must hand it the reference once at app start. This applies to both Old and New Architecture — the JNI lookup depends on _buildConfig being set in UltimateConfigHelper.

Solution: Add to MainApplication.kt:

import com.reactnativeultimateconfig.UltimateConfigModule

override fun onCreate() {
    super.onCreate()
    UltimateConfigModule.setBuildConfig(BuildConfig::class.java)
}

iOS: empty config at runtime (`npx rncu` not run before build)

Symptom: Config.MY_VAR returns undefined on iOS. The following warning appears in Metro / the Xcode console at startup:

[UltimateConfig] No config values found. Did you run `npx rncu <env-file>` and rebuild the iOS app? Required on both Old and New Architecture.

Why: Unlike Android (which reads values via reflection at runtime), iOS bakes values into a generated ConfigValues.h header at build time. If the header was never generated, or was generated from an empty .env, getValues() returns @{} and JS receives an empty config.

Solution:

Generate the header with your env file:
```
npx rncu .env
```

Verify it contains your variables (not a placeholder):

cat node_modules/react-native-config-ultimate/ios/ConfigValues.h

Full rebuild (the new header is picked up by the Objective-C compiler, not by Metro):
```
cd ios && pod install && cd ..
npx react-native run-ios
```

The warning fires once per process via dispatch_once, so it won’t spam your console. It’s printed from both Old Arch (constantsToExport) and New Arch (getAll) code paths.

Still Stuck?

Check the API Reference for correct usage
See Monorepo Tips for workspace setups
Open an issue with:
- React Native version (npx react-native --version)
- Library version (npm list react-native-config-ultimate)
- Architecture (Old or New)
- Full error message
- Your monorepo setup (if applicable)

Troubleshooting

Environment variables for React Native that just work

Troubleshooting

Quick Fixes

Table of Contents

Build Issues

Build fails with “Source env file(s) changed since the rncu CLI was last run”

Build fails with “requires Gradle 7.4 or newer”

Divergence error after CRLF / line ending change

Missing config files error

CI/CD builds failing

Runtime Issues

Android: Empty config object `{}`

Values are undefined at runtime

TypeScript: Property does not exist on type

CLI Issues

“command not found” or “use strict: command not found”

CLI writes to wrong location in monorepo

Monorepo Issues

Android: Can’t find gradle-plugin or react-native

pnpm: Various resolution errors

rncu.yaml not found during build

Platform-Specific Issues

Android: “DEBUG” variable causes build error

iOS: rncu.xcconfig not found

iOS: ConfigValues.h not generated

Web: Module not found

Metro: “Unable to resolve module”

Architecture-Specific Issues

New Architecture: TurboModule not found

Android: setBuildConfig not called (empty config at runtime)

iOS: empty config at runtime (`npx rncu` not run before build)

Still Stuck?

Troubleshooting

Quick Fixes

Table of Contents

Build Issues

Build fails with “Source env file(s) changed since the rncu CLI was last run”

Build fails with “requires Gradle 7.4 or newer”

Divergence error after CRLF / line ending change

Missing config files error

CI/CD builds failing

Runtime Issues

Android: Empty config object {}

Values are undefined at runtime

TypeScript: Property does not exist on type

CLI Issues

“command not found” or “use strict: command not found”

CLI writes to wrong location in monorepo

Monorepo Issues

Android: Can’t find gradle-plugin or react-native

pnpm: Various resolution errors

rncu.yaml not found during build

Platform-Specific Issues

Android: “DEBUG” variable causes build error

iOS: rncu.xcconfig not found

iOS: ConfigValues.h not generated

Web: Module not found

Metro: “Unable to resolve module”

Architecture-Specific Issues

New Architecture: TurboModule not found

Android: setBuildConfig not called (empty config at runtime)

iOS: empty config at runtime (npx rncu not run before build)

Still Stuck?

Android: Empty config object `{}`

iOS: empty config at runtime (`npx rncu` not run before build)