Amazing CLIfor Terminal
Runbook

Troubleshooting

Common integration issues and debugging

Git2Docs Certified

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:

    // CommonJS, Node.js ≥22.12 only
    const chalk = require('chalk').default;
    
  2. Switch to an ESM import (recommended for all Node.js ≥ 22 versions):

    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:

    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:

    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:

    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.

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:

    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:

    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).

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

    // 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:

    npm install chalk-template
    

    Then 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.

  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:

    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:

    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.

ConditionDetected Level
Chromium brand version > 93 (via userAgentData)3
Other Chrome/Chromium user agent string1
Non-Chromium browser or navigator absent0

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:

    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:

    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:

    // 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.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:

    git checkout package.json
    
  2. Uninstall Chalk if you decide not to proceed with the integration:

    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 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.