---
title: Troubleshooting
product: amazing-cli
doc_type: runbook
version: main
source: git2docs (code-derived, validation-filtered)
canonical: https://git2docs.com/wabam/docs/amazing-cli/chalk/troubleshooting
---

# Troubleshooting

_Common integration issues and debugging_

## Objective

This runbook helps you diagnose and resolve the most common integration problems encountered when installing and using Chalk in a Node.js or browser project.

## Scope

Covers: ESM/CommonJS import errors, color not appearing in output, incorrect or missing color levels, chaining and template literal mistakes, environment variable conflicts, browser detection issues, and invalid level errors.

Does **not** cover: Chalk internals, vendored module customization, CI/CD pipeline setup beyond environment variable guidance, or issues specific to bundlers not related to Chalk's ESM-only format.

## Prerequisites

Before working through this runbook, confirm the following:

- **Node.js ≥ 22** is installed (`node --version`).
- Chalk is installed in your project: `npm install chalk`.
- Your project uses ES modules (`"type": "module"` in `package.json`, or `.mjs` file extensions).
- You can reproduce the problem in a minimal script that imports Chalk.

## Steps

### Issue 1 — `ERR_REQUIRE_ESM` when calling `require('chalk')`

Chalk is ESM-only. The behavior of `require('chalk')` depends on your Node.js version.

**Node.js 22.0–22.11:** `require('chalk')` throws `ERR_REQUIRE_ESM`. There is no CommonJS build.

1. **Upgrade to Node.js ≥ 22.12** if you must use `require()`. On Node.js ≥ 22.12, `require('chalk')` succeeds and returns the ES module namespace. Access the default export via `.default`:

   ```js
   // CommonJS, Node.js ≥22.12 only
   const chalk = require('chalk').default;
   ```

2. **Switch to an ESM import** (recommended for all Node.js ≥ 22 versions):

   ```js
   import chalk from 'chalk';
   ```

   Set `"type": "module"` in your `package.json`, or rename the file to `.mjs`.

**How you know it worked:** The import resolves without error and `typeof chalk` is `'function'`.

---

### Issue 2 — Output appears with no color (plain text only)

Chalk suppresses color when it detects a non-TTY stream or a terminal with level 0.

1. **Check the detected color level** by logging `chalk.level` immediately after import:

   ```js
   import chalk from 'chalk';
   console.log(chalk.level); // 0 = no color, 1–3 = color enabled
   ```

2. **If `chalk.level` is `0`**, the terminal does not support color or color has been suppressed. Diagnose further:

   - Is the output being piped? Piped streams are not TTYs, so color is disabled automatically.
   - Is `TERM=dumb` set in the environment? This signals a dumb terminal and forces level 0.
   - Is `FORCE_COLOR=0` set? This explicitly disables color regardless of terminal detection.

3. **Force color on for testing** using the `FORCE_COLOR` environment variable:

   ```sh
   FORCE_COLOR=1 node your-script.js   # Basic 16-color
   FORCE_COLOR=2 node your-script.js   # 256-color
   FORCE_COLOR=3 node your-script.js   # Truecolor
   ```

   `FORCE_COLOR=true` (or an empty value) enables color and lets the level be detected from the terminal; a numeric value pins the level exactly (capped at 3).

4. **For a specific isolated context** (e.g., a module that must not affect global state), create a custom instance instead of overriding `chalk.level` globally:

   ```js
   import { Chalk } from 'chalk';

   const customChalk = new Chalk({ level: 3 });
   console.log(customChalk.red('Forced red'));
   ```

**How you know it worked:** `chalk.level` returns a value > 0 and styled output appears with color in the terminal.

---

### Issue 3 — `FORCE_COLOR` and `--no-color` conflict

A common misconception is that `--no-color` unconditionally disables color. In Chalk's vendored `supports-color` logic:

- A **non-zero numeric `FORCE_COLOR`** value replaces the result of the `--color`/`--no-color` flag check. So `FORCE_COLOR=1 node script.js --no-color` gives **level 1**, not 0.
- `FORCE_COLOR=0` disables color regardless of any flag.
- `--color=256` and `--color=16m` take precedence over a non-zero numeric `FORCE_COLOR`.

**Resolution:** When you need to disable color unconditionally in scripts or CI, use `FORCE_COLOR=0` rather than relying solely on `--no-color`.

```sh
FORCE_COLOR=0 node your-script.js
```

**How you know it worked:** `chalk.level` is `0` and no ANSI codes appear in output.

---

### Issue 4 — Chaining styles produces unexpected visual output

When conflicting styles of the same type are chained (e.g., `chalk.red.yellow`), **all ANSI open codes are emitted**, but only the last one is visually applied. The chain `chalk.red.yellow` renders yellow text, and `chalk.yellow.red` renders red text — the last color in the chain wins visually.

1. **Review your chain order.** The last style of a conflicting type is the one the terminal displays:

   ```js
   chalk.red.yellow('text')   // Visually yellow
   chalk.yellow.red('text')   // Visually red
   ```

2. **Remove redundant styles** to keep output predictable and strings clean of extra escape codes.

3. **Note on builder identity:** Each style property access returns a **new cached builder function**, not the same instance. Storing a partial chain is safe and expected:

   ```js
   const error = chalk.bold.red;   // Reusable builder
   console.log(error('Something failed'));
   ```

**How you know it worked:** The terminal renders the color you intended, and you have no duplicate style properties in the chain.

---

### Issue 5 — Tagged template literals do not interpolate correctly

Core Chalk does **not** support tagged template literals. Using `chalk.red\`text ${val}\`` does not interpolate `val` in place — the raw string array is coerced and values are appended after a space, producing misplaced output (e.g., `chalk.green\`Hello ${name}\`` yields `"Hello ,"` with the name misplaced).

1. **Replace tagged template syntax with a regular function call:**

   ```js
   // Wrong — do not use
   chalk.red`Hello ${name}`

   // Correct
   chalk.red(`Hello ${name}`)
   ```

2. **If you need tagged template literal support with correct interpolation**, install the companion package:

   ```sh
   npm install chalk-template
   ```

   Then use it as documented in [chalk-template](https://github.com/chalk/chalk-template).

**How you know it worked:** The interpolated variable appears inline within the styled string, not displaced after a space.

---

### Issue 6 — `Error: The \`level\` should be an integer from 0 to 3`

This error is thrown by the `Chalk` constructor or by assigning to `chalkInstance.level` when the value is not a safe integer in the range 0–3.

1. **Check the value you are passing.** Common causes:
   - Passing a float (e.g., `1.5`).
   - Passing a string (e.g., `'2'`).
   - Passing `null`, `NaN`, or a number outside 0–3.

2. **Guard `supportsColor` before reading `.level`**, because `supportsColor` and `supportsColorStderr` can be `false` when color is not detected:

   ```js
   import { supportsColor } from 'chalk';
   import { Chalk } from 'chalk';

   const level = supportsColor ? supportsColor.level : 0;
   const customChalk = new Chalk({ level });
   ```

3. **Omit the `level` option entirely** to let Chalk auto-detect:

   ```js
   import { Chalk } from 'chalk';
   const customChalk = new Chalk(); // Level auto-detected
   ```

**How you know it worked:** No error is thrown and `customChalk.level` returns an integer between 0 and 3.

---

### Issue 7 — No color in browser / browser bundle

Chalk uses a separate color detector for non-Node environments, resolved via the `default` condition in `package.json` imports (not a `browser` condition). It inspects `navigator` and `userAgentData`.

| Condition | Detected Level |
|---|---|
| Chromium brand version > 93 (via `userAgentData`) | 3 |
| Other Chrome/Chromium user agent string | 1 |
| Non-Chromium browser or `navigator` absent | 0 |

Note: Since Chrome 69, ANSI escape codes are natively supported in the developer console.

1. **Confirm the browser/runtime exposes `navigator`.** If `navigator` is not present in `globalThis`, the level is 0.

2. **If you need a specific level in a browser bundle**, create a custom instance:

   ```js
   import { Chalk } from 'chalk';
   const chalk = new Chalk({ level: 3 });
   ```

**How you know it worked:** Styled strings appear with color when logged to the Chrome DevTools console.

---

### Issue 8 — `chalkStderr` not applying styles

`chalkStderr` is a separate Chalk instance configured from the color support of `stderr` (not `stdout`). If `stderr` is not a TTY (e.g., redirected to a file), its level may be 0 independently of `chalk.level`.

1. **Check `supportsColorStderr`** before styling stderr output:

   ```js
   import { chalkStderr, supportsColorStderr } from 'chalk';

   if (supportsColorStderr) {
     console.error(chalkStderr.red('Error text'));
   } else {
     console.error('Error text');
   }
   ```

2. **Force stderr color level** using `FORCE_COLOR` (applies to both stdout and stderr detection).

**How you know it worked:** `supportsColorStderr` is a truthy `ColorSupport` object and `chalkStderr.level` is > 0.

## Verification

After resolving your issue, verify the integration is working correctly:

1. **Level check:** Run the following minimal script from your project root:

   ```js
   // verify-chalk.mjs
   import chalk from 'chalk';
   import { supportsColor, supportsColorStderr } from 'chalk';

   console.log('chalk.level:', chalk.level);
   console.log('supportsColor:', supportsColor);
   console.log('supportsColorStderr:', supportsColorStderr);
   console.log(chalk.green('✓ Green text'));
   console.log(chalk.bold.red('✓ Bold red text'));
   console.log(chalk.hex('#FFA500')('✓ Orange via hex'));
   ```

   ```sh
   node verify-chalk.mjs
   ```

   **Expected results:**
   - `chalk.level` is a whole number from 0 to 3 (greater than 0 for a color-capable terminal).
   - `supportsColor` is either `false` or an object with a `level` property.
   - The three styled lines appear with the described formatting in a supported terminal.

2. **No `ERR_REQUIRE_ESM`:** If you are on Node.js ≥ 22.12 and using `require()`, confirm that `require('chalk').default` is a function.

3. **No misplaced interpolation:** Confirm that `chalk.green('Hello ' + name)` produces inline output with the value in position.

## Rollback

Chalk is a library with no persistent side effects on your system — it does not modify files, start services, or write to databases. To undo any changes made while following this runbook:

1. **Revert `package.json` changes** (e.g., if you added `"type": "module"`) using your version control system:

   ```sh
   git checkout package.json
   ```

2. **Uninstall Chalk** if you decide not to proceed with the integration:

   ```sh
   npm uninstall chalk
   ```

3. **Remove forced environment variables** (`FORCE_COLOR`, `COLORTERM`, etc.) from shell profiles, `.env` files, or CI configuration that you added during debugging.

4. **Revert any Node.js version change** by switching back to your previous version using your version manager (e.g., `nvm use <previous-version>`).

No further rollback is required because Chalk makes no persistent changes outside your project's dependency installation.

## Escalation

If you have worked through all steps in this runbook and the problem persists, escalate as follows:

1. **Collect diagnostic information before reporting:**
   - Node.js version: `node --version`
   - npm version: `npm --version`
   - Chalk version: `npm list chalk`
   - The value of `chalk.level` in your environment
   - The values of relevant environment variables: `FORCE_COLOR`, `TERM`, `COLORTERM`, `CI`, and any CI-specific variables
   - A minimal reproduction script (the smallest `.mjs` file that shows the problem)
   - The full error message and stack trace if an exception is thrown

2. **Search existing issues** at [https://github.com/chalk/chalk/issues](https://github.com/chalk/chalk/issues) to check whether the problem is already reported or has a known workaround.

3. **Open a new issue** on the Chalk GitHub repository if no existing issue matches. Include all diagnostic information collected in step 1 and a clear description of the expected versus actual behavior.

4. **For organization-internal issues** (e.g., corporate proxy blocking npm, internal bundler configuration), escalate to your infrastructure or DevOps team with the diagnostic information above rather than filing an upstream issue.
