Course: React Native Training
Topic: Troubleshooting Build Failures, Deployment Errors, and Production Issues
Course Link: React Native Training at JustAcademy
Demo Link: Register for a Free Course Demo
Learning Resource: JustAcademy
React Native allows developers to build Android and iOS applications using JavaScript or TypeScript and React. Although much of the application code can be shared across platforms, building and releasing a React Native application involves several different systems, including Metro, Node.js, native Android tooling, Xcode, Gradle, CocoaPods, signing certificates, app-store services, APIs, and device-specific configurations.
A React Native application may run correctly in development mode but fail when creating a release build or installing the production version. Problems can also occur after deployment, such as application crashes, failed API requests, authentication errors, slow performance, or incorrect environment configuration.
Troubleshooting is the systematic process of identifying the cause of a problem, verifying the diagnosis, applying a safe fix, and confirming that the application works as expected.
A build failure occurs when the development tools cannot successfully compile, bundle, package, or sign an application.
Common examples include:
A deployment error occurs when an application cannot be installed, uploaded, distributed, or released successfully.
Examples include an APK that cannot be installed, an Android App Bundle rejected by Google Play, an iOS archive that cannot be uploaded, an invalid signing configuration, or an application that fails to launch after installation.
A production issue affects users who are using a released application. These problems may not appear during development because production builds use different optimizations, environment variables, permissions, network configurations, and error-handling behavior.
Examples include unexpected crashes, blank screens, API timeouts, expired authentication tokens, failed payments, corrupted local data, and performance problems on older devices.
Before troubleshooting, developers should understand the major stages involved in converting source code into a distributable application.
| Stage | Typical Problem | First Investigation |
|---|---|---|
| Dependency installation | Package installation or version conflict | Package manager output and lockfile |
| JavaScript bundling | Missing module or syntax error | Metro output and import paths |
| Android compilation | Gradle or SDK failure | Gradle task output and tool versions |
| iOS compilation | Xcode or CocoaPods failure | Xcode logs, pod configuration, deployment target |
| Signing | Invalid credentials or profile | Signing configuration |
| Installation | Package conflict or incompatible device | Device logs and package metadata |
| Runtime | Crash, blank screen, failed request | Crash report, device logs, network traces |
| Distribution | Store validation or upload failure | Store validation messages and app metadata |
The most effective way to troubleshoot a React Native application is to follow a repeatable process instead of randomly changing configuration files.
Identify the exact action that causes the issue. Determine whether it occurs during dependency installation, bundling, compilation, signing, installation, application launch, or a particular user interaction.
Record the following information:
Build logs can contain many secondary errors caused by one underlying problem. Find the earliest meaningful failure rather than focusing only on the final line that reports that the build failed.
For example, a Gradle build may finish with a generic message stating that the build failed. The actual cause might be an incompatible Java version, a missing Android SDK platform, or a native dependency that cannot compile.
Review recent changes to application code, dependencies, environment variables, build scripts, signing settings, and native configuration.
If the problem appeared immediately after a change, test a controlled rollback or compare the affected files with the last known working version.
Changing several settings simultaneously makes it difficult to determine which change resolved the issue. Modify one relevant setting, rebuild, and record the result before making another change.
After resolving the error, repeat the failing operation. Test the affected platform and build variant, and check for regressions in related functionality.
React Native applications depend on JavaScript packages as well as native libraries. Missing, incompatible, or incorrectly installed dependencies can prevent an application from bundling or compiling.
For an npm-based project, run:
node --version
npm --version
npm ls --depth=0These commands help identify the installed runtime and top-level dependencies. Review warnings and invalid dependency versions before making changes.
For a project that uses npm and has a committed package-lock.json file, use:
npm ciThe command installs dependencies from the lockfile and is suitable for reproducible CI builds. It can remove the existing node_modules directory, so use it in the correct project directory and ensure that the lockfile represents the intended dependencies.
For Yarn or pnpm projects, use the appropriate frozen-lockfile or immutable installation workflow supported by the package manager version in use.
Check the import statement, file name, file extension, package installation, and capitalization.
// Example of a local component import
import ProfileCard from './components/ProfileCard';
// Verify that the file exists at the expected path.
// On case-sensitive file systems, capitalization must match.A path that works on one developer's machine may fail on a case-sensitive CI or Linux environment if the actual file name uses different capitalization.
Upgrading every dependency to its newest version may introduce additional incompatibilities. Review React Native compatibility, native module requirements, and release notes before upgrading a package.
Metro is the JavaScript bundler commonly used by React Native. It resolves imports, transforms source code, and packages application modules and assets.
If logs suggest stale transformation or resolution data, stop the development server and restart it with a cleared cache:
npx react-native start --reset-cacheThis command is useful for some development-server problems. It does not repair incorrect imports, incompatible dependencies, or native compilation errors.
Release builds typically bundle JavaScript rather than relying on a development server running on the developer's computer. A build that works only while Metro is running may indicate a release bundling, asset inclusion, or configuration problem.
Check the native build logs and the project's build configuration to confirm that the release bundle is generated and packaged correctly.
Verify that referenced images and fonts exist, that their paths are correct, and that the asset types are supported by the build configuration.
import { Image } from 'react-native';
export default function Logo() {
return (
<Image
source={require('./assets/logo.png')}
style={{ width: 120, height: 60 }}
resizeMode="contain"
/>
);
}The example assumes that the asset exists at the specified path relative to the source file.
React Native Android builds commonly use Gradle, the Android Gradle Plugin, the Android SDK, and Java. Native modules may also introduce additional compilation requirements.
| Error Category | Possible Cause | Recommended Action |
|---|---|---|
| Gradle configuration failure | Invalid build script or plugin configuration | Inspect the first Gradle configuration error |
| Java compatibility error | Unsupported JDK or toolchain combination | Check the project's required Java version |
| SDK not found | Missing SDK platform or incorrect SDK path | Install the required platform and verify local configuration |
| Dependency resolution failure | Unavailable artifact, repository issue, or version conflict | Check repository access and dependency declarations |
| Manifest merge error | Conflicting manifest attributes | Review the detailed manifest merger report |
| Native compilation failure | Incompatible C++ code, NDK, or native module | Inspect the failing compiler task and toolchain versions |
| Signing failure | Missing or incorrect signing configuration | Verify the release signing settings securely |
Run the following commands from the project directory:
java -version
cd android
./gradlew --versionOn Windows Command Prompt, use:
java -version
cd android
gradlew.bat --versionCompare the reported versions with the requirements of the project's Gradle wrapper, Android Gradle Plugin, and React Native version. Do not assume that installing the newest JDK is always the correct fix.
For a typical React Native Android project, use:
cd android
./gradlew assembleDebugFor a release APK, a common command is:
./gradlew assembleReleaseThe exact task and output depend on the project configuration. Projects with product flavors may require a flavor-specific task.
To obtain more diagnostic output, use:
./gradlew assembleDebug --stacktraceUse the equivalent gradlew.bat command on Windows.
Open the project in Android Studio and verify that the SDK platform, build tools, and any required NDK or CMake versions are installed. Confirm that the configured SDK path points to the intended local installation.
A missing SDK component should be installed at the version required by the project rather than by arbitrarily changing the project's compile SDK settings.
When logs suggest stale native build outputs, a Gradle clean can help:
cd android
./gradlew cleanBuild again after cleaning. A clean build can remove generated outputs, but it will not resolve incorrect dependencies, unsupported tool versions, or invalid source code.
Android libraries can contribute manifest entries that conflict with the application's own manifest. Inspect the manifest merger report and identify the exact conflicting attributes before changing the manifest.
Do not remove permissions, exported component declarations, or security-related settings merely to make the build pass. Confirm that the final manifest preserves the application's intended behavior and security requirements.
React Native iOS builds use Xcode, Apple build tools, native dependencies, and usually CocoaPods for dependency management. iOS development and signing generally require macOS and the relevant Apple tooling.
Run the following commands on a Mac:
xcodebuild -version
xcode-select -p
pod --versionCheck that the selected Xcode installation is the one intended for the project and that the required command-line tools are available.
From the React Native project directory, run:
cd ios
pod installIf dependency resolution fails, review the exact pod error, repository availability, the Podfile, and the project's supported deployment target. Follow the dependency's documented requirements before changing versions.
After modifying native dependencies, open the workspace generated by CocoaPods when the project uses one. Opening only the project file may omit required pod integration.
Open the iOS workspace in Xcode, select the correct scheme, and inspect the first failing build step. Verify:
For distribution, Apple signing settings must match the application identifier, team, certificate, provisioning profile, and enabled capabilities. Expired or mismatched signing assets can prevent archiving, uploading, or installation.
Use Xcode's signing diagnostics and the organization's approved credential-management process. Never share private signing keys or certificates with private keys in logs, screenshots, or public repositories.
Expo projects may use Expo's managed tooling, native projects generated through prebuild, or custom native code. The appropriate troubleshooting steps depend on the project's workflow and configuration.
Useful commands include:
npx expo-doctor
npx expo install --checkThese checks can help identify configuration problems and package versions that may not match the project's Expo SDK. Review the output and confirm that any suggested changes are appropriate for the application.
Check the project's eas.json file and verify that the selected profile has the intended distribution type, environment, platform settings, and channel or update configuration where applicable.
{
"build": {
"development": {
"developmentClient": true,
"distribution": "internal"
},
"preview": {
"distribution": "internal"
},
"production": {}
}
}This is an illustrative example. Actual build profiles should be adapted to the project's Expo SDK, release requirements, and distribution workflow.
When an EAS build fails, identify the failed phase in the build logs. A failure during dependency installation requires a different investigation from a failure during native compilation or signing.
Check the package manager, lockfile, native dependency configuration, environment variables, and signing credentials relevant to the failing phase. Avoid assuming that every cloud build failure is an Expo service problem.
Changing native dependencies or configuration may require a new native build. Updating JavaScript alone does not automatically add new native code to an already-installed binary.
A release build may compile successfully but crash, display a blank screen, or behave differently from the debug build. Release mode may change JavaScript bundling, optimization, logging, environment configuration, and native behavior.
Whenever possible, install and test a release-like build before distributing it to users. Verify application startup, authentication, navigation, network access, file uploads, notifications, payments, and other critical workflows.
For Android, a locally generated release APK can be installed on a test device when the build configuration supports that workflow. For iOS, use an appropriate signed development, ad hoc, or TestFlight distribution workflow.
A blank screen may result from an uncaught JavaScript exception, failed initial API request, invalid navigation state, unavailable configuration, or a native startup failure.
Check device logs and crash reports, add safe error boundaries where appropriate, and ensure the application has a visible loading state and a useful error state rather than waiting indefinitely.
Review imports and initialization code for tools that should only be used in development. Confirm that production configuration does not rely on a local Metro server, local filesystem path, debugging proxy, or development-only API endpoint.
Applications often use different API endpoints and feature settings for development, staging, and production. Incorrect configuration can cause the application to compile successfully but fail as soon as it makes a request.
Use one clearly defined configuration module rather than scattering endpoint strings across components.
// config/api.ts
export const API_BASE_URL = 'https://api.example.com';
// services/userService.ts
import { API_BASE_URL } from '../config/api';
export async function getUsers() {
const response = await fetch(`${API_BASE_URL}/users`);
if (!response.ok) {
throw new Error(`Request failed: ${response.status}`);
}
return response.json();
}The example uses a placeholder domain. Replace it with the appropriate configured endpoint for the intended environment.
React Native application bundles can be inspected by users. API keys, passwords, private tokens, and other confidential credentials should not be treated as secret merely because they are stored in environment variables during the build.
Use a secure backend for privileged operations and keep sensitive credentials on infrastructure that the client cannot inspect. Public client identifiers may be necessary for certain SDKs, but they should be restricted according to the provider's security recommendations.
Verify the endpoint, HTTP method, authentication header, request body, response status, timeout behavior, and server availability. Test the same environment that the production application uses.
For HTTPS errors, inspect certificate validity and the server's TLS configuration. Do not disable certificate validation as a production workaround.
Network failures can occur because of connectivity problems, incorrect URLs, expired tokens, server errors, DNS issues, TLS configuration, or platform-specific network security restrictions.
| Status or Symptom | Possible Meaning | What to Check |
|---|---|---|
| 400 | Invalid request | Request payload, parameter types, endpoint contract |
| 401 | Missing or invalid authentication | Token, session state, token refresh workflow |
| 403 | Access denied | User permissions, scopes, server access policy |
| 404 | Resource not found | API path, resource identifier, environment |
| 429 | Rate limit exceeded | Request frequency, retry policy, server limits |
| 500-series | Server-side failure | Backend logs, service health, dependency availability |
| Timeout | Request did not finish in time | Network conditions, server latency, timeout settings |
export async function fetchProfile(token: string) {
try {
const response = await fetch(
'https://api.example.com/profile',
{
headers: {
Authorization: `Bearer ${token}`,
},
}
);
if (response.status === 401) {
throw new Error('Authentication required.');
}
if (!response.ok) {
throw new Error(`Request failed: ${response.status}`);
}
return await response.json();
} catch (error) {
// Send safe diagnostic information to an approved logger.
// Avoid logging tokens, passwords, or personal data.
throw error;
}
}This example demonstrates basic response checking. A production application should also define suitable timeouts, cancellation behavior, retry rules, and user-facing error messages.
Retries can help with temporary network failures, but they should not be applied indiscriminately. Use bounded retries with backoff for suitable operations. Avoid automatically repeating payments or other non-idempotent actions unless the backend supports safe idempotency controls.
A crash occurs when the operating system terminates the application or an unrecoverable native or JavaScript failure prevents normal execution.
Use Android device logs, Xcode device logs, platform crash reports, and an approved crash-reporting service. Record the application version, device model, operating-system version, and reproduction steps.
For Android, a common diagnostic command is:
adb logcatFor iOS, inspect the device logs and crash reports available through Xcode and the relevant Apple distribution tools.
Validate data before accessing nested properties, particularly when values arrive from remote APIs or local storage.
type User = {
profile?: {
displayName?: string;
};
};
function getDisplayName(user: User | null | undefined) {
return user?.profile?.displayName ?? 'Guest';
}Optional chaining and fallback values reduce some runtime errors, but they do not replace validation of the data contract or appropriate error handling.
Use representative data volumes, network conditions, and authentication states to reproduce crashes. A bug that appears only for a particular account or large response may not occur with a small development dataset.
Performance issues can make an application feel unreliable even when it does not crash. Production users may have older devices, slower networks, limited memory, and larger datasets than developers use during testing.
Use React Native's supported debugging and profiling tools, platform profilers, and production performance telemetry. Identify the actual bottleneck before adding memoization or rewriting components.
For large collections, use React Native's virtualized list components and provide stable keys. Avoid rendering an entire large dataset inside a basic ScrollView when a virtualized list is more appropriate.
import { FlatList, Text } from 'react-native';
type Product = {
id: string;
name: string;
};
export function ProductList({
products,
}: {
products: Product[];
}) {
return (
<FlatList
data={products}
keyExtractor={(item) => item.id}
renderItem={({ item }) => (
<Text>{item.name}</Text>
)}
/>
);
}Clean up subscriptions, event listeners, and other resources when they are no longer needed. Avoid updating state after a component has become irrelevant to the active workflow, and cancel requests where the API and application lifecycle allow it.
Features such as push notifications, camera access, location, file selection, and background execution depend on native configuration, device permissions, and external services.
Verify that required permissions are declared correctly and requested at the appropriate time. A permission declaration alone does not guarantee that a user has granted access.
Emulators and simulators are useful but may not fully reproduce hardware, permission, background execution, notification, or vendor-specific behavior. Include real-device testing for important device-dependent features.
A successful local build does not guarantee that an application will be accepted by a distribution platform. Store submission involves package metadata, versioning, signing, policy requirements, and platform validation.
Android uses a version code to identify successive application releases and a version name for the user-facing version label. A new upload generally needs an acceptable version code that does not conflict with an existing release for the same application.
Review the Gradle configuration and store error message before changing versioning settings.
iOS applications use a user-facing version and a build number. Ensure the build number satisfies the distribution workflow and is appropriate for the uploaded build.
Read the complete validation message and identify whether it concerns signing, package metadata, platform compatibility, permissions, privacy declarations, or application behavior. Resolve the specific issue and upload a new build when required.
Store requirements can change. Consult the official platform documentation for the requirements applicable to the release being submitted.
Continuous integration (CI) systems automatically install dependencies, run tests, and generate builds. A project may work locally but fail in CI because the environment differs from the developer's machine.
Pin the supported toolchain where appropriate, commit the correct lockfile, document build commands, and use consistent dependency installation procedures. Avoid depending on untracked local files or manually configured settings that CI cannot reproduce.
# Example npm-based validation workflow
node --version
npm ci
npm test -- --runInBand
npx tsc --noEmitAdapt the test command to the project's test runner. TypeScript validation is useful when the project uses TypeScript and has a configured compiler. These steps do not replace the native Android or iOS build.
Store signing credentials and other sensitive build values in the CI platform's protected secret-management facility. Restrict access to authorized workflows and people, and avoid printing secret values to build logs.
Production troubleshooting becomes more effective when applications provide safe, structured diagnostic information. Developers should be able to understand failures without exposing sensitive user information.
Prefer logs with consistent fields and severity levels, such as debug, info, warning, and error. Reduce noisy diagnostic logging in production while retaining sufficient information for incident investigation.
Never log passwords, authentication tokens, payment details, private keys, or unnecessary personal information. Apply appropriate access controls and retention limits to crash reports and telemetry.
Track crash frequency, affected versions, common stack traces, and changes following releases. A rise in crashes immediately after a deployment may indicate a regression that should be investigated quickly.
When a production issue affects users, restoring a reliable experience may be more important than immediately implementing a complete long-term solution.
Consider rolling back or halting a rollout when a release causes a serious regression and a safe rollback path is available. A rollback may not immediately remove an already installed mobile application from devices, so the recovery strategy depends on the distribution platform and release mechanism.
A hotfix should be focused, tested, reviewed, and traceable. Avoid unverified changes to signing, permissions, authentication, payment handling, or other security-sensitive features just to restore functionality quickly.
The following table summarizes useful commands. Run them from the appropriate project directory and adapt them to the project's tooling.
| Purpose | Command | Use |
|---|---|---|
| Check Node.js | node --version |
Verify the JavaScript runtime version |
| Check npm | npm --version |
Verify the package manager version |
| Inspect packages | npm ls --depth=0 |
Review installed top-level dependencies |
| Install from npm lockfile | npm ci |
Perform a reproducible dependency installation |
| Reset Metro cache | npx react-native start --reset-cache |
Investigate selected Metro cache issues |
| Check Expo setup | npx expo-doctor |
Identify selected Expo configuration issues |
| Check Java | java -version |
Verify the installed Java runtime |
| Check Gradle | ./gradlew --version |
Inspect Gradle and JVM details |
| Clean Android outputs | ./gradlew clean |
Remove generated Gradle build outputs |
| Build Android debug | ./gradlew assembleDebug |
Test an Android debug build |
| Inspect Android logs | adb logcat |
View device and application logs |
| Check Xcode | xcodebuild -version |
Inspect the installed Xcode version |
| Install iOS pods | pod install |
Install native iOS dependencies |
Important: The Android Gradle wrapper uses gradlew.bat on Windows. Commands, task names, and build requirements can vary by React Native version, project structure, operating system, and build workflow.
Document supported tool versions, commit dependency lockfiles, and standardize development and CI environments. Upgrade React Native and native dependencies deliberately rather than mixing unrelated upgrades.
Use unit tests for business logic, component tests for UI behavior, integration tests for important services, and end-to-end tests for critical user journeys.
Before distributing an application, test installation, startup, authentication, navigation, API requests, offline behavior, permissions, and critical business operations on supported devices.
Keep development, staging, and production settings distinct. Verify the selected environment and API endpoint before creating a production build.
Where the distribution platform supports it, release to a limited audience first. Monitor crashes, performance, and support reports before increasing the rollout.
Project objective: Practice investigating a React Native application that works in development but fails during release build or after installation.
A mobile application works correctly while connected to the development server. However, the Android release build fails in CI. After the build issue is corrected, a test release installs successfully but cannot load the user's profile because the application is using the wrong API endpoint.
Answer: A build failure prevents the application from being compiled, bundled, packaged, or signed. A runtime failure occurs when the application is executing, such as a crash, blank screen, or failed API request.
Answer: Release builds may use different bundling, optimization, environment configuration, native settings, and logging behavior. Testing a release-like build helps identify these differences.
Answer: Metro is the JavaScript bundler commonly used by React Native. It resolves imports, transforms code, and bundles JavaScript modules and assets.
Answer: Reset the cache when symptoms suggest stale Metro transformation or module-resolution data. It is not a general solution for invalid source code or native compilation errors.
Answer: Read the first meaningful error, inspect the failing task, verify Java and Gradle compatibility, check SDK components and dependency versions, and use diagnostic output such as a stack trace.
Answer: Common causes include incompatible pod versions, invalid Podfile configuration, repository or network issues, unsupported deployment targets, and native dependency conflicts.
Answer: A lockfile records resolved dependency versions, helping developers and CI systems install a consistent dependency set and reduce unexpected build differences.
Answer: Collect the crash report, stack trace, application version, device and OS information, and reproduction steps. Identify the affected code path and verify the fix on the relevant release build.
Answer: An APK is an installable Android package. An Android App Bundle is a publishing format from which distribution services can generate optimized APKs for devices.
Answer: Expo Application Services Build is a service for building Android and iOS applications using Expo's build tooling and configured project workflow.
Answer: Missing or incorrect configuration can cause the app to use the wrong API endpoint, omit required settings, or initialize services incorrectly. Configuration should be verified for each build environment.
Answer: Confidential credentials should not be embedded in the client bundle because client applications can be inspected. Privileged operations and secrets should be handled on a secure backend.
Answer: Check connectivity, DNS and TLS behavior, request duration, server health, endpoint configuration, and timeout settings. Use bounded retries only when appropriate.
Answer: A hotfix is a focused correction released to address an urgent problem. It should still undergo appropriate review, testing, and monitoring.
Answer: Real devices reveal hardware, permission, performance, background execution, and operating-system behaviors that may not be fully represented by simulators or emulators.
Answer: Read the store's validation message, identify whether the issue concerns signing, versioning, metadata, compatibility, privacy, or policy, and correct the specific problem before resubmitting.
Answer: Use consistent tool versions, committed lockfiles, reproducible installation commands, protected secrets, automated tests, and clear build logs.
Answer: Crash monitoring helps teams identify recurring failures, determine which versions and devices are affected, prioritize fixes, and verify that releases improve stability.
Troubleshooting build failures, deployment errors, and production issues is an essential skill for React Native developers. Successful troubleshooting requires an understanding of JavaScript dependencies, Metro, native Android and iOS build systems, signing, release configuration, network behavior, and production monitoring.
The most reliable approach is to reproduce the issue, inspect the logs, identify the root cause, apply a focused fix, and verify the result in a realistic environment. Reproducible builds, automated testing, secure configuration, structured logging, and careful release monitoring can prevent many recurring problems.
By practicing these methods, developers can deliver React Native applications that are more stable, secure, maintainable, and reliable for users.
