How to Fix Android 14 PDF ENOENT Crashes in React Native New Architecture

INTRODUCTION

While working on a FinTech application designed to provide secure access to user financial statements, our engineering team initiated an upgrade to React Native version 0.82.1. To leverage performance improvements and synchronous native integrations, we enabled the New Architecture (TurboModules and Fabric). The deployment was progressing smoothly until quality assurance teams began reporting intermittent, unrecoverable app crashes.

We realized these crashes were strictly isolated to devices running Android 14 (API 34). Specifically, the application would terminate abruptly when a user attempted to open and view a remote PDF statement on a fresh install or immediately after clearing the app cache.

We encountered a situation where standard error boundaries and try-catch blocks completely failed to trap the exception. The app simply crashed to the home screen. In the highly regulated FinTech industry, abrupt crashes during document retrieval severely damage user trust and fail basic compliance audits.

This challenge inspired the following deep dive. Below, we break down how our team uncovered a filesystem race condition triggered by the New Architecture, how we stabilized the implementation, and why this matters for teams planning similar upgrades.

PROBLEM CONTEXT

The core business requirement was to securely download, cache, and render encrypted PDF financial statements from a remote server. To handle this, the architecture relied on a standard combination of a popular React Native PDF rendering component and a blob utility library for filesystem management.

In our component, we configured the PDF viewer to handle caching automatically, which is a standard pattern for minimizing network requests on subsequent document opens:

<DocumentViewer
  source={{
    uri: 'https://secure-api.example.com/statements/v1/doc.pdf',
    cache: true,
  }}
  onError={(error) => handleError(error)}
/>

In legacy React Native applications using the old bridge, this configuration worked flawlessly. The underlying blob utility would download the file to a temporary cache directory, create a .pdf.tmp file, and pass the local path to the PDF renderer.

However, running this precise configuration under Android 14 with the New Architecture enabled (newArchEnabled=true) fundamentally altered how the application interacted with device I/O streams, leading to catastrophic failure.

WHAT WENT WRONG

When investigating the crash, we noticed the application wasn’t failing gracefully. The onError prop on the document viewer was never invoked. Instead, the crash surfaced in the logs as an unhandled promise rejection that escaped the component’s lifecycle completely:

Uncaught (in promise, id: 0):
Error: /data/user/0/com.generic.fintech/cache/a1b2c3d4.pdf.tmp:
open failed: ENOENT (No such file or directory)

The symptoms were highly specific:

• Bypassed Error Handling: The underlying native promise rejected globally, bypassing the internal .catch() handler attached to the blob utility task.
• State of the Filesystem: The cache directory (CacheDir) resolved correctly, and the generated temporary file path string was syntactically valid.
• The Missing File: When the system attempted the open/read operation, the .pdf.tmp file did not physically exist on disk.
• Strict Reproduction Constraints: The crash was strictly reproducible on Android 14 with New Architecture enabled. It did not reproduce on Android 13, nor did it reproduce when falling back to the old React Native bridge.

HOW WE APPROACHED THE SOLUTION

Our initial diagnostic steps focused on Android 14’s storage permission changes, but we quickly ruled out permissions because the cache directory does not require explicit user consent. The focus shifted to the execution timing of TurboModules.

Under the old React Native bridge, asynchronous calls between the JavaScript thread and native modules carried a slight serialization overhead. This overhead inadvertently acted as a buffer, allowing asynchronous file I/O operations (like creating a temp file) to complete before subsequent native code tried to read from it.

With TurboModules and JSI, JavaScript invokes native methods synchronously or with significantly reduced latency. We deduced that a race condition was occurring in the cache/temp-file flow of the third-party PDF and blob libraries. The .pdf.tmp file was being requested by the PDF renderer mere milliseconds before the blob utility had initialized the write stream on disk, causing the Android OS to throw an immediate ENOENT.

We faced an architectural choice: attempt to patch the third-party libraries using patch-package, or redesign our document rendering architecture to decouple the download phase from the rendering phase. Because relying on black-box caching mechanisms is generally unsafe for mission-critical enterprise applications, we opted to architect a custom, robust download layer.

FINAL IMPLEMENTATION

To definitively resolve the race condition, we stripped the caching responsibility away from the PDF viewing component. Instead, we implemented an explicit, verifiable pre-fetching mechanism that ensures the file exists completely on disk before the rendering component ever mounts.

1. Decoupling Download from Rendering

We created a custom hook to manage the secure download to the application’s document directory (avoiding the volatile cache directory). We implemented explicit existence checks before yielding the URI to the UI layer.

const useSecureDocument = (remoteUri) => {
  const [localUri, setLocalUri] = useState(null);
  const [error, setError] = useState(null);
  useEffect(() => {
    let isMounted = true;
    
    const fetchAndVerifyDocument = async () => {
      try {
        const fileName = generateHash(remoteUri) + '.pdf';
        const targetPath = `${DocumentDirectory}/${fileName}`;
        
        // Check if fully downloaded previously
        const exists = await FileSystem.exists(targetPath);
        if (exists) {
          if (isMounted) setLocalUri(`file://${targetPath}`);
          return;
        }
        // Await full file download completion
        await FileSystem.downloadAsync(remoteUri, targetPath);
        
        // Explicit verification step to defeat race conditions
        const verifyExists = await FileSystem.exists(targetPath);
        if (!verifyExists) throw new Error('File verification failed post-download');
        if (isMounted) setLocalUri(`file://${targetPath}`);
      } catch (err) {
        if (isMounted) setError(err);
      }
    };
    fetchAndVerifyDocument();
    return () => { isMounted = false; };
  }, [remoteUri]);
  return { localUri, error };
};

2. Updating the View Component

With the file explicitly downloaded and verified, we updated the PDF component to consume the local file URI and strictly disabled its internal caching.

const StatementScreen = ({ uri }) => {
  const { localUri, error } = useSecureDocument(uri);
  if (error) return <ErrorFallback message={error.message} />;
  if (!localUri) return <LoadingSpinner />;
  return (
    <DocumentViewer
      source={{
        uri: localUri,
        cache: false, // Critical: bypass internal race condition
      }}
      onError={(err) => logToTelemetry(err)}
    />
  );
};

By enforcing an explicit sequential flow—download entirely, verify existence, render from verified local path—we eliminated the TurboModule race condition. The unhandled promise rejections disappeared, and Android 14 performance stabilized.

LESSONS FOR ENGINEERING TEAMS

When organizations need to hire software developer teams to modernize critical platforms, understanding the deep systemic impacts of framework upgrades is essential. Here are the core insights from this resolution:

• TurboModules Expose Hidden Timing Bugs: The New Architecture removes the asynchronous delay of the old bridge. If older native modules relied on that delay for file operations to complete, they will fail randomly.
• Decouple Core Concerns: Never combine network fetching, file I/O caching, and complex UI rendering in a single third-party black-box prop (like cache: true). Separating these layers provides control and observability. This level of architectural foresight is exactly why CTOs choose to hire react native developers for enterprise modernization.
• Implement Global Rejection Handlers: Ensure your React Native application utilizes a global unhandled promise rejection tracker. In this instance, the library’s internal .catch() failed, meaning telemetry would be blind without global tracking.
• Verify Filesystem State: Never assume a file exists just because a download promise resolves. The OS filesystem synchronization can lag behind JavaScript execution. Always execute an explicit existence check before attempting to read.
• Isolate Bleeding-Edge OS Testing: OS-specific file system restrictions (like those in Android 14) combined with framework upgrades often create isolated crash matrices. Testing must be segmented specifically for the newest API levels. Organizations looking to hire mobile developers for scalable systems must prioritize comprehensive edge-case testing.

WRAP UP

Upgrading to React Native’s New Architecture offers incredible performance gains, but it requires a vigilant approach to asynchronous behaviors that were previously masked by the old bridge. By identifying the ENOENT race condition on Android 14 and decoupling the document download process from the rendering engine, we secured a stable, crash-free experience for our users. When you hire app developers for production deployment, ensuring they possess the capability to trace these deep native issues is critical for long-term success. If your team is navigating complex mobile architecture upgrades and needs pre-vetted, expert engineering support, contact us.

Social Hashtags

#ReactNative #Android14 #MobileDevelopment #TurboModules #ReactNativeNewArchitecture #AndroidDevelopment #JavaScript #FinTech #AppDevelopment #SoftwareEngineering #Fabric #JSI #MobileApps #Programming #TechBlog