Troubleshooting

This runbook helps you diagnose and resolve the most common issues encountered when integrating Chalk into a Node.js application, including missing colors, broken output, and API misuse.

Covered:

• Chalk producing no color output or plain text
• Incorrect or unexpected color rendering
• Import and module system errors (CommonJS vs. ESM)
• Color level detection and manual override
• Chaining API errors
• Template literal tag issues

Not covered:

• Terminal emulator configuration or OS-level color support
• Non-Node.js runtimes (e.g., Deno, Bun) beyond general guidance
• Custom Chalk instance internals or plugin development
• Issues unrelated to Chalk itself (e.g., upstream logging framework conflicts)

Before working through this runbook, ensure you have the following in place:

• Node.js — A supported LTS version (check the Chalk README for the minimum required version)
• Chalk — Installed in your project (npm list chalk confirms it is present)
• A terminal emulator — One that supports ANSI escape codes (most modern terminals do; Windows users should prefer Windows Terminal or VS Code's integrated terminal)
• Access to your project's package.json — To verify module type ("type": "module" or CommonJS)
• Basic familiarity with Node.js module imports and your project's build or run toolchain

Work through these steps in order. Each step targets a specific class of problem — stop as soon as your issue is resolved.

Step 1 — Confirm Chalk is installed correctly

Run the following in your project root:

npm list chalk

You should see Chalk listed as a dependency with a version number. If it is missing or shows UNMET DEPENDENCY, install it:

npm install chalk

Success: npm list chalk shows a resolved version with no warnings.

Step 2 — Verify your import syntax matches your module system

Chalk v5+ is ESM-only. If your project uses CommonJS (require()), you must either use Chalk v4 or migrate your project to ESM.

ESM (Chalk v5+):

import chalk from 'chalk';

CommonJS (Chalk v4):

const chalk = require('chalk');

To check your project's module type, inspect package.json:

{ "type": "module" }

If "type" is absent or set to "commonjs", your project is CommonJS.

Success: Your file imports Chalk without a module resolution error and chalk is a valid object in scope.

Step 3 — Check the detected color level

Chalk auto-detects color support. If it detects no support, all styling is silently stripped. Add this diagnostic line temporarily:

import chalk from 'chalk';
console.log('Color level:', chalk.level);

If chalk.level is 0, Chalk has detected a non-color-capable environment (common in CI pipelines, piped output, or certain editors).

Success: chalk.level is 1, 2, or 3.

Step 4 — Manually override the color level (if Step 3 shows level 0)

You can force color output by setting the level directly — useful in CI environments or when piping output:

import chalk from 'chalk';
chalk.level = 3; // Force truecolor
console.log(chalk.green('Forced color output'));

Alternatively, many CI systems and CLIs respect the FORCE_COLOR environment variable:

FORCE_COLOR=1 node your-script.js

Success: The terminal displays styled output after the override.

Step 5 — Validate your chaining syntax

Chalk's API is chainable. Each style is a property or method call on the Chalk instance. A common mistake is calling styles as functions when they are properties, or vice versa.

Correct chaining:

console.log(chalk.bold.red('Error message'));
console.log(chalk.bgBlue.white.underline('Highlighted'));

Incorrect — styles are not standalone strings:

// Wrong: red is not a string
console.log(chalk.red + ' some text');

// Wrong: calling a non-function style
console.log(chalk.bold.red.underline());
// 'underline' with no argument returns a Chalk instance, not a string

Chalk styles that accept colors (e.g., rgb(), hex(), bgRgb()) are methods and require arguments:

console.log(chalk.hex('#FFA500').bold('Orange and bold'));
console.log(chalk.rgb(255, 165, 0)('Orange via RGB'));

Success: Your styled string renders correctly in the terminal without undefined, [object Object], or empty output.

Step 6 — Debug template literal usage

Chalk supports tagged template literals. Ensure you are using the correct syntax — the tag is a style chain, not a plain function call:

const name = 'world';
// Correct
console.log(chalk.green`Hello, ${name}!`);

// Also correct — explicit call with interpolated string
console.log(chalk.green(`Hello, ${name}!`));

If interpolated values appear unstyled or missing, check that your template literal expressions evaluate to strings or numbers (Chalk does not deeply style nested Chalk calls inside template literals by default).

Success: Interpolated values appear inside the styled string as expected.

Step 7 — Isolate the issue with a minimal reproduction

If none of the above steps resolved your problem, create a minimal script that reproduces the issue in isolation:

// test-chalk.mjs  (or test-chalk.js with "type":"module")
import chalk from 'chalk';

console.log('Chalk level:', chalk.level);
console.log(chalk.red('Red text'));
console.log(chalk.bold.blue('Bold blue text'));
console.log(chalk.hex('#FF8800')('Orange hex'));

Run it directly:

node test-chalk.mjs

Compare the output of this isolated script with your application's behavior. If the isolated script works but your app does not, the issue likely lies in how Chalk is being called within your application's specific context (e.g., a logging wrapper stripping ANSI codes, a bundler transformation, or an incorrect import).

Success: You can pinpoint whether the issue is Chalk itself or the surrounding code.

After completing the applicable steps, verify the runbook succeeded by checking the following observable outcomes:

1. Color output is visible — Running your application or the minimal test script produces styled, colored text in your terminal.

2. No import errors — Your application starts without ERR_REQUIRE_ESM, Cannot find module 'chalk', or SyntaxError related to imports.

3. chalk.level is non-zero — A quick console.log(chalk.level) in your code returns 1, 2, or 3.

4. Chained styles render correctly — Methods like chalk.bold.red('text') and chalk.hex('#FF0000')('text') output the expected styled strings.

5. No raw escape codes in output — If your terminal supports color, you should see formatted text, not raw ANSI sequences like \u001b[31m. Raw sequences appearing in output suggest ANSI codes are being double-escaped or written to a non-TTY consumer without being stripped.

Most Chalk troubleshooting steps are non-destructive (diagnostic logging and configuration changes), but if you made changes that need to be reverted:

Reverting a forced color level: If you hardcoded chalk.level = 3 in your source code as a workaround, remove that line and allow Chalk to auto-detect the level again:

// Remove this line from your code:
chalk.level = 3;

Reverting a Chalk version downgrade: If you downgraded from Chalk v5 to v4 to resolve a CommonJS compatibility issue, you can upgrade again after migrating your project to ESM:

npm install chalk@latest

Remember to update your import statements back to ESM syntax after upgrading.

Reverting FORCE_COLOR environment variable: If you set FORCE_COLOR in a shell profile, CI configuration, or .env file, remove or unset it:

unset FORCE_COLOR

Removing the diagnostic test file: Delete any temporary files created during Step 7:

rm test-chalk.mjs

If you have worked through all steps and your issue is still unresolved, escalate as follows:

1. Search existing issues first

Search the Chalk GitHub Issues to check whether your problem is a known bug or has an existing workaround. Use specific search terms like your error message or the behavior you are observing.

2. Open a new GitHub issue

If no existing issue matches, open a new one. Include the following information to enable maintainers to reproduce and diagnose the problem:

• Chalk version (npm list chalk)
• Node.js version (node --version)
• Operating system and terminal emulator
• Module system (ESM or CommonJS)
• Minimal reproduction script (from Step 7) — the smallest possible code that demonstrates the problem
• Actual output vs. expected output — if possible, include a screenshot or copied terminal output
• chalk.level value at the time the issue occurs
• Any relevant environment variables (e.g., TERM, COLORTERM, FORCE_COLOR, NO_COLOR)

3. Community support

For general integration questions that may not be bugs, consider asking on Stack Overflow with the tags node.js and chalk or in relevant developer communities (e.g., the Nodeiflux Discord).