# Understanding the Error Code System in Material-UI: How Errors Are Minified

> Discover Material-UI's error code system. Learn how MUI uses descriptive messages in development and minified codes in production to optimize bundle size.

- Repository: [MUI/material-ui](https://github.com/mui/material-ui)
- Tags: internals
- Published: 2026-02-26

---

**Material-UI (MUI) implements a centralized numeric error code system that displays full, descriptive messages during development but emits minified codes in production to minimize bundle size.**

The error code system in Material-UI provides a consistent mechanism for reporting runtime issues—such as invalid props or incorrect component usage—while ensuring that production builds remain lightweight. Located in the `@mui/material` package, this system relies on two core utilities that switch between verbose development messages and compact production codes based on the `NODE_ENV` environment variable.

## Core Components of the Material-UI Error System

### The `error` Utility Function

The primary entry point for all runtime errors is the `error` function defined in [`packages/mui-material/src/utils/error.ts`](https://github.com/mui/material-ui/blob/main/packages/mui-material/src/utils/error.ts). This utility accepts a **numeric error code** and optional interpolation values, then constructs an `Error` object with either a full description or a minified string depending on the environment.

### The Message Registry (`formatMuiErrorMessage`)

Error message templates are stored in [`packages/mui-material/src/utils/formatMuiErrorMessage.ts`](https://github.com/mui/material-ui/blob/main/packages/mui-material/src/utils/formatMuiErrorMessage.ts). This file exports `formatMuiErrorMessage`, which maintains a lookup table mapping numeric codes to message strings containing placeholders (`%s`). When the `error` utility runs in development, it calls this function to populate the template with runtime values.

### Environment-Based Message Selection

The system uses `process.env.NODE_ENV` to determine output format:

- **Development** (`NODE_ENV !== 'production'`): Returns the full, interpolated message with component names and prop values
- **Production**: Returns a minified string containing only `MUI: <code>`, drastically reducing the bytes shipped to clients

## How the Error Code System Works in Practice

When a component detects invalid usage, it invokes the `error` utility with a specific code:

1. **Define the error**: Each distinct error receives a unique numeric identifier (e.g., `100`, `101`, `102`) registered in [`formatMuiErrorMessage.ts`](https://github.com/mui/material-ui/blob/main/formatMuiErrorMessage.ts):

```typescript
// excerpt from formatMuiErrorMessage.ts
const errorMessages: Record<number, string> = {
  100: 'MUI: The `component` prop must be a string, an HTML element, or a function.',
  101: 'MUI: The prop `%s` is unsupported on the %s component.',
  // …
};

```

2. **Trigger the error**: Components call `error` with the code and interpolation values:

```typescript
import { error } from '@mui/material/utils';

if (invalidProp) {
  error(101, propName, componentName);
}

```

3. **Receive context-aware output**: In development, the developer sees the full message with specific prop names. In production, users see only `MUI: 101`, preventing bundle bloat while maintaining debuggability through the documented error code reference.

## How Errors Are Minified in Production

The minification process strips all descriptive text from production bundles. When `error` detects a production environment, it bypasses the message interpolation entirely and returns a string in the format:

```

MUI: 101

```

This approach achieves several optimization goals:

- **Bundle size reduction**: Error message strings often contain lengthy explanations and component names. By shipping only numeric codes, MUI eliminates kilobytes of descriptive text from production builds.
- **Consistent debugging**: Each numeric code maps to a specific entry in the MUI documentation at `https://mui.com/material-ui/guides/minimizing-bundle-size/#error-codes`, allowing developers to look up full explanations when production logs show only the code.
- **Runtime performance**: The minified path requires no string interpolation or object lookups, making error throwing marginally faster in production.

## Code Examples

### Example 1: Throwing an Error Inside a Component

```tsx
import React from 'react';
import { error } from '@mui/material/utils';

interface MyButtonProps {
  variant?: 'contained' | 'outlined';
  wrongProp?: number;
}

export const MyButton = (props: MyButtonProps) => {
  if (typeof props.wrongProp === 'number') {
    // 100 is the code for "unsupported prop type"
    error(100);
  }

  return <button>{props.children}</button>;
};

```

**Development output:**

```

MUI: The `wrongProp` prop must be a string, an HTML element, or a function.

```

**Production output:**

```

MUI: 100

```

### Example 2: Using the Error Helper with Interpolation

```ts
import { error } from '@mui/material/utils';

function validateProps(align: string, direction: string) {
  if (align === 'center' && direction !== 'row') {
    // 101 corresponds to "invalid prop combination"
    error(101, align, direction);
  }
}

```

### Example 3: Looking Up Full Messages Programmatically

```ts
import formatMuiErrorMessage from '@mui/material/utils/formatMuiErrorMessage';

const fullMessage = formatMuiErrorMessage(101, 'center', 'column');
// => "MUI: The prop `center` is unsupported on the column component."

```

## Summary

- Material-UI centralizes error handling through the `error` utility in [`packages/mui-material/src/utils/error.ts`](https://github.com/mui/material-ui/blob/main/packages/mui-material/src/utils/error.ts), which accepts numeric codes and optional interpolation values.
- Full error messages are stored in [`packages/mui-material/src/utils/formatMuiErrorMessage.ts`](https://github.com/mui/material-ui/blob/main/packages/mui-material/src/utils/formatMuiErrorMessage.ts), mapping codes to descriptive templates with placeholders.
- The system uses `process.env.NODE_ENV` to switch between verbose development messages and minified production codes (e.g., `MUI: 101`), significantly reducing bundle size.
- Developers can look up minified codes in the official MUI documentation to retrieve full explanations and debugging context.

## Frequently Asked Questions

### What do the numeric error codes in Material-UI mean?

Each numeric code represents a specific runtime error condition, such as an invalid prop type or unsupported component configuration. The codes are defined in [`formatMuiErrorMessage.ts`](https://github.com/mui/material-ui/blob/main/formatMuiErrorMessage.ts) and correspond to detailed message templates. When you encounter a code like `MUI: 101` in production, you can look up the full explanation on the MUI error codes documentation page.

### How do I debug a minified Material-UI error in production?

When you see a minified error such as `MUI: 100` in your production logs or error tracking service, note the numeric code and visit the Material-UI documentation section on error codes. The documentation provides a lookup table mapping each code to its full description, including which props or components triggered the error and how to resolve the issue.

### Why does Material-UI use numeric error codes instead of full messages?

Material-UI uses numeric error codes to minimize production bundle size. Error messages often contain lengthy strings describing prop validation failures and component usage guidelines. By stripping these strings from production builds and replacing them with compact numeric identifiers, MUI reduces the kilobytes shipped to end users while maintaining a debuggable development experience.

### Where are the error code definitions located in the Material-UI source?

The error code definitions reside in [`packages/mui-material/src/utils/formatMuiErrorMessage.ts`](https://github.com/mui/material-ui/blob/main/packages/mui-material/src/utils/formatMuiErrorMessage.ts). This file exports a lookup object that maps numeric codes to message templates containing placeholders for dynamic values. The `error` function in [`packages/mui-material/src/utils/error.ts`](https://github.com/mui/material-ui/blob/main/packages/mui-material/src/utils/error.ts) consumes these definitions to generate appropriate messages based on the current environment.