We've all been there. You've spent weeks building a new feature. You've tested every edge case, your local development server is humming along perfectly, and every pull request has gone green. You merge, deploy, and then it happens: the Slack alert. The feature that was flawless on your machine is a blank white screen in production. The dreaded phrase echoes in your mind: "But… it worked on my machine." This is one of the most frustrating experiences in web development, but it's also a universal one. The gap between your local environment and a live production server is filled with subtle differences that can turn perfectly good code into a critical bug. This guide will walk you through the seven most common reasons why this happens. We'll explain the root causes, show you how to reproduce them, and provide practical fixes you can apply today to make your React applications more robust. ## TL;DR: The 7 Most Common Causes For those in a hurry, here's the quick rundown of what we'll be covering: 1. **Environment Differences**: Your code is running with different variables (NODE_ENV), API endpoints, or feature flags. 2. **Race Conditions**: Faster production servers and network speeds change the timing of asynchronous operations, revealing hidden bugs. 3. **Minification & Bundling Issues**: The build process mangles code in unexpected ways, breaking logic that relies on function or property names. 4. **Missing Polyfills**: Your code uses modern JavaScript features that aren't supported by all user browsers, and you only tested on the latest version of Chrome. 5. **Dependency Mismatches**: The node_modules on the server are slightly different from your local setup, causing version conflicts. 6. **Inconsistent Data Shapes**: An API returns a slightly different data structure in production, causing your components to crash when they try to render undefined. 7. **Missing Error Boundaries**: A small, uncaught error in one component crashes the entire application because there's nothing to contain the blast radius. ## First Steps: Is This a Production-Only Crash? Before you start hunting for obscure causes, you need to confirm that the bug is truly specific to a production environment. Your first goal is to recreate the production environment on your local machine. ### 1. Run a Production Build Locally Your local development server (`npm start`) is optimized for hot-reloading and debugging, not for performance. It skips many of the steps that a production build goes through, like [minification](https://learn.microsoft.com/en-us/aspnet/mvc/overview/performance/bundling-and-minification) and [tree-shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking). The first thing you should always do is build the app for production and serve it locally. ```bash # Build the application for production npm run build # Serve the static files from the 'build' directory # If you don't have 'serve', install it with: npm install -g serve serve -s build ``` This simple step often reveals issues caused by the build process itself. If the app crashes now, you've narrowed your search significantly. ### 2. Check Your Browser's Developer Tools Open the developer console and look for errors. A production error might look cryptic due to minification, like `Uncaught TypeError: a.b is not a function` in `main.cbe934.js`. This is where [source maps](https://web.dev/articles/source-maps) are essential. A source map is a file that maps your compiled, minified code back to your original source code. If your build process generates source maps, your browser's dev tools can use them to show you the exact line in your original component file that caused the error. ## Cause 1: Environment Differences This is, by far, the most common culprit. Your frontend code often behaves differently based on environment variables. **Why it fails in production**: In a typical React setup, `process.env.NODE_ENV` is set to `'development'` locally and `'production'` when you build. Your code might check this variable to enable or disable logging, developer tools, or other features. More importantly, your server URLs, API keys, and feature flags are almost always different between environments. A classic example is forgetting to update your `.env.production` file, causing your app to make API calls to `http://localhost:8080` instead of `https://api.yourcompany.com`. **How to detect and fix it**: First, ensure you have separate environment configuration files (e.g., `.env.development`, `.env.production`). ```bash # .env.development REACT_APP_API_URL=http://localhost:8080 REACT_APP_FEATURE_FLAG_NEW_DASHBOARD=true # .env.production REACT_APP_API_URL=https://api.yourcompany.com REACT_APP_FEATURE_FLAG_NEW_DASHBOARD=false ``` Second, check your production server's configuration to make sure it's loading these variables correctly. Add logging at the start of your application to print out the key environment variables (and then remove it once you've confirmed). Finally, never hardcode environment-specific values. Always reference them through `process.env`. ## Cause 2: Race Conditions and Async Timing Race conditions are bugs that only appear when events happen in an unexpected order. These are notoriously difficult to find because they depend on timing, which is very different in production. **Why it fails in production**: Your production servers and CDN are likely much faster than your local machine. An API call that takes 800ms locally might only take 100ms in production. This change in timing can expose race conditions. A common example occurs in a `useEffect` hook that fetches data. Imagine a user lands on a page, the data fetch begins, but they quickly navigate to another page before the fetch completes. ```javascript // A classic race condition bug function UserProfile({ id }) { const [user, setUser] = useState(null); useEffect(() => { // Flag to track if the component is still mounted let isMounted = true; fetchUserProfile(id).then(userData => { // If the component has unmounted, this will cause a memory leak warning // and potentially bugs if the user data is stale on the next render. if (isMounted) { setUser(userData); } }); // The cleanup function return () => { isMounted = false; }; }, [id]); if (!user) { return

; } return

{user.name}

; } ``` Locally, the data fetch is slow, so you never see the error. In production, the fetch is so fast that the state update might try to happen after the component has already unmounted, leading to a React state update warning or unpredictable behavior. **How to detect and fix it**: The fix is to use a cleanup function in your `useEffect` hook to track whether the component is still mounted. The code above includes this fix. The `isMounted` flag is set to false when the component unmounts, preventing `setUser` from being called. For modern React, using an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) to cancel the fetch request is an even better approach. ![Race conditions in React components](/images/blog/35/race-conditions.png) ## Cause 3: Minification and Bundler Issues The build tools that bundle your code for production (like [Webpack](https://webpack.js.org/) with [Terser](https://terser.org/)) perform aggressive optimizations. They shorten variable names and restructure code to reduce file size. **Why it fails in production**: Sometimes, these optimizations can break your code. For example, if you have code that relies on the string name of a function or a class (`myFunction.name`), minification might change that name to `a`, causing your logic to fail. This can also affect libraries that use reflection or similar dynamic techniques. **How to detect and fix it**: This is another case where running the production build locally (`npm run build && serve -s build`) is your best diagnostic tool. Use your source maps to trace the minified error back to your original code. If you find a mangled name is the issue, you can often configure your bundler to prevent it from changing specific names. Here's a Terser configuration example in a `webpack.config.js` to keep class names: ```javascript // webpack.config.js module.exports = { // ... other config optimization: { minimizer: [ new TerserPlugin({ terserOptions: { keep_classnames: true, keep_fnames: true, }, }), ], }, }; ``` ## Cause 4: Missing Polyfills and Browser Differences You might be using modern JavaScript features like `Array.prototype.at()` or `Object.fromEntries()`. While these work in the latest version of Chrome on your developer machine, they might not be supported in older browsers that your users have. **Why it fails in production**: Your development environment doesn't represent the vast matrix of browsers and versions your users are on. Your app crashes for a user on an older version of Safari or Firefox because the JavaScript engine doesn't recognize the syntax. **How to detect and fix it**: The solution is to use [polyfills](https://developer.mozilla.org/en-US/docs/Glossary/Polyfill). A polyfill is a piece of code that provides the functionality you're missing. Tools like Babel and core-js can automatically include the polyfills you need based on a `browserslist` configuration in your `package.json`. ```json // package.json "browserslist": { "production": [ ">0.2%", "not dead", "not op_mini all" ], "development": [ "last 1 chrome version", "last 1 firefox version", "last 1 safari version" ] } ``` This configuration tells Babel to only include polyfills required by browsers with more than 0.2% market share, ensuring a good balance between compatibility and bundle size. --- **Mid-Article CTA**: Tired of manually trying to recreate production bugs? The right tool can capture the exact runtime context—DOM, network, and console state—the moment a bug occurs. theORQL is building a tool to do just that. Learn more and join our [early access waitlist](/signup). --- ## Cause 5: External Dependency Mismatches The `node_modules` directory is famously complex. A tiny difference in a sub-dependency version between your local machine and the production server can cause major issues. **Why it fails in production**: This usually happens when your `package-lock.json` or `yarn.lock` file is out of sync or not being used correctly during deployment. If the CI/CD server runs `npm install` instead of `npm ci`, it might install slightly different versions of your dependencies than what you tested with locally. **How to detect and fix it**: Always commit your lock file (`package-lock.json` or `yarn.lock`) to version control. In your deployment scripts, use `npm ci` instead of `npm install`. The `npm ci` command does a clean install based only on the versions specified in your lock file, guaranteeing that the `node_modules` directory is identical in every environment. ## Cause 6: Inconsistent Data Shapes from APIs Your component expects a user object to always have a `user.profile.avatarUrl` property. It works perfectly locally because your mock data is consistent. **Why it fails in production**: In the real world, data is messy. The production API might return a user object where the `profile` key is null or missing entirely for some users. Your code then tries to access `null.avatarUrl` and the entire component tree crashes. **How to detect and fix it**: The best way to prevent this is with [defensive coding](https://en.wikipedia.org/wiki/Defensive_programming). Never assume an object property exists. Use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) (`?.`) and [nullish coalescing](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing) (`??`) to safely access nested properties and provide fallback values. ```javascript // Unsafe - will crash if user.profile is null const avatar = user.profile.avatarUrl; // Safe - will return undefined if profile is null const safeAvatar = user?.profile?.avatarUrl; // Even safer - provides a fallback image const finalAvatar = user?.profile?.avatarUrl ?? '/default-avatar.png'; ``` For larger applications, consider using a library like Zod or Yup to validate the shape of API responses as soon as you receive them, ensuring that malformed data is caught at the source. ## Cause 7: Unhandled Exceptions & Missing Error Boundaries In a large React application, a single, uncaught JavaScript error in a minor component can crash the entire page. **Why it fails in production**: React's development mode error overlays are forgiving, but in production, any unhandled error during rendering will cause React to unmount the entire component tree, resulting in a blank page. **How to detect and fix it**: React has a built-in solution for this: Error Boundaries. An Error Boundary is a special React component that catches JavaScript errors anywhere in its child component tree, logs those errors, and displays a fallback UI instead of the component tree that crashed. Here is a simple example: ```javascript import React from 'react'; class ErrorBoundary extends React.Component { constructor(props) { super(props); this.state = { hasError: false }; } static getDerivedStateFromError(error) { // Update state so the next render will show the fallback UI. return { hasError: true }; } componentDidCatch(error, errorInfo) { // You can also log the error to an error reporting service logErrorToMyService(error, errorInfo); } render() { if (this.state.hasError) { // You can render any custom fallback UI return

Something went wrong. Please try again.

; } return this.props.children; } } ``` You can then wrap parts of your application with it. It's a good practice to place error boundaries around major UI sections, like a sidebar, header, or the main content area. ```jsx