Troubleshooting
Common integration issues and debugging
Git2Docs CertifiedThis runbook helps you diagnose and resolve the most common integration problems encountered when installing and using Chalk in a Node.js or browser project.
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.
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"inpackage.json, or.mjsfile extensions). - You can reproduce the problem in a minimal script that imports Chalk.
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.
-
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:// CommonJS, Node.js ≥22.12 only const chalk = require('chalk').default; -
Switch to an ESM import (recommended for all Node.js ≥ 22 versions):
import chalk from 'chalk';Set
"type": "module"in yourpackage.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.
-
Check the detected color level by logging
chalk.levelimmediately after import:import chalk from 'chalk'; console.log(chalk.level); // 0 = no color, 1–3 = color enabled -
If
chalk.levelis0, 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=dumbset in the environment? This signals a dumb terminal and forces level 0. - Is
FORCE_COLOR=0set? This explicitly disables color regardless of terminal detection.
-
Force color on for testing using the
FORCE_COLORenvironment variable: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 # TruecolorFORCE_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). -
For a specific isolated context (e.g., a module that must not affect global state), create a custom instance instead of overriding
chalk.levelglobally: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_COLORvalue replaces the result of the--color/--no-colorflag check. SoFORCE_COLOR=1 node script.js --no-colorgives level 1, not 0. FORCE_COLOR=0disables color regardless of any flag.--color=256and--color=16mtake precedence over a non-zero numericFORCE_COLOR.
Resolution: When you need to disable color unconditionally in scripts or CI, use FORCE_COLOR=0 rather than relying solely on --no-color.
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.
-
Review your chain order. The last style of a conflicting type is the one the terminal displays:
chalk.red.yellow('text') // Visually yellow chalk.yellow.red('text') // Visually red -
Remove redundant styles to keep output predictable and strings clean of extra escape codes.
-
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:
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 interpolatevalin 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).
-
Replace tagged template syntax with a regular function call:
// Wrong — do not use chalk.red`Hello ${name}` // Correct chalk.red(`Hello ${name}`) -
If you need tagged template literal support with correct interpolation, install the companion package:
npm install chalk-templateThen use it as documented in 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.
-
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.
- Passing a float (e.g.,
-
Guard
supportsColorbefore reading.level, becausesupportsColorandsupportsColorStderrcan befalsewhen color is not detected:import { supportsColor } from 'chalk'; import { Chalk } from 'chalk'; const level = supportsColor ? supportsColor.level : 0; const customChalk = new Chalk({ level }); -
Omit the
leveloption entirely to let Chalk auto-detect: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.
-
Confirm the browser/runtime exposes
navigator. Ifnavigatoris not present inglobalThis, the level is 0. -
If you need a specific level in a browser bundle, create a custom instance:
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.
-
Check
supportsColorStderrbefore styling stderr output:import { chalkStderr, supportsColorStderr } from 'chalk'; if (supportsColorStderr) { console.error(chalkStderr.red('Error text')); } else { console.error('Error text'); } -
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.
After resolving your issue, verify the integration is working correctly:
-
Level check: Run the following minimal script from your project root:
// 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'));node verify-chalk.mjsExpected results:
chalk.levelis a whole number from 0 to 3 (greater than 0 for a color-capable terminal).supportsColoris eitherfalseor an object with alevelproperty.- The three styled lines appear with the described formatting in a supported terminal.
-
No
ERR_REQUIRE_ESM: If you are on Node.js ≥ 22.12 and usingrequire(), confirm thatrequire('chalk').defaultis a function. -
No misplaced interpolation: Confirm that
chalk.green('Hello ' + name)produces inline output with the value in position.
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:
-
Revert
package.jsonchanges (e.g., if you added"type": "module") using your version control system:git checkout package.json -
Uninstall Chalk if you decide not to proceed with the integration:
npm uninstall chalk -
Remove forced environment variables (
FORCE_COLOR,COLORTERM, etc.) from shell profiles,.envfiles, or CI configuration that you added during debugging. -
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.
If you have worked through all steps in this runbook and the problem persists, escalate as follows:
-
Collect diagnostic information before reporting:
- Node.js version:
node --version - npm version:
npm --version - Chalk version:
npm list chalk - The value of
chalk.levelin your environment - The values of relevant environment variables:
FORCE_COLOR,TERM,COLORTERM,CI, and any CI-specific variables - A minimal reproduction script (the smallest
.mjsfile that shows the problem) - The full error message and stack trace if an exception is thrown
- Node.js version:
-
Search existing issues at https://github.com/chalk/chalk/issues to check whether the problem is already reported or has a known workaround.
-
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.
-
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.