Tutorial: Debug a Node.js Error

This walkthrough covers the full Spark workflow — from hitting an error to sharing your refined solution — using a common real-world scenario.

Scenario: You're migrating a Node.js project to ESM (ECMAScript Modules) and hit ERR_MODULE_NOT_FOUND.

Hit the error

You're converting a Node.js project from CommonJS to ESM. You update your require() calls to import statements, run the project, and get:

node:internal/errors:496
    ErrorCaptureStackTrace(err);
    ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/Users/dev/project/src/utils'
imported from /Users/dev/project/src/index.js
    at finalizeResolution (node:internal/modules/esm/resolve:264:11)
    at moduleResolve (node:internal/modules/esm/resolve:910:10)

You know this is an ESM issue, but the fix isn't obvious. Time to query the network.

Query Spark

Ask Spark for community-validated solutions. Include the full error text and add semantic tags to narrow results to your stack:

spark --pretty query "ERR_MODULE_NOT_FOUND Cannot find module" \
  --tag language:node:20 \
  --tag task_type:bug_fix

💡

Always include the full error text in your query for better matches. "ERR_MODULE_NOT_FOUND Cannot find module" will return more relevant results than just "ESM import error".

Read the recommendations

Spark returns a ranked list of community-validated solutions:

Session: abc123

Recommendations for: "ERR_MODULE_NOT_FOUND Cannot find module"
Tags: language:node:20, task_type:bug_fix

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[0] ESM migration: add "type": "module" and fix import paths
    Confidence: 94%  |  Validations: 127  |  Source: community
    ──────────────────────────────────────────────
    When migrating to ESM, Node.js requires two changes:
    1. Add "type": "module" to package.json
    2. Use full file extensions in relative imports (./utils.js, not ./utils)

[1] ERR_MODULE_NOT_FOUND with TypeScript + ESM
    Confidence: 82%  |  Validations: 43  |  Source: community
    ──────────────────────────────────────────────
    If using TypeScript, set "module": "node16" and "moduleResolution": "node16"
    in tsconfig.json. Import paths must use .js extensions even for .ts files.

[2] __dirname and __filename in ESM
    Confidence: 78%  |  Validations: 89  |  Source: community
    ──────────────────────────────────────────────
    __dirname is not available in ESM. Replace with:
    import { fileURLToPath } from 'url';
    const __dirname = path.dirname(fileURLToPath(import.meta.url));

The top result has a 94% confidence score and 127 community validations. That's a strong signal.

Drill into the details

The CLI returns ranked summaries. To pull the full body of a recommendation — code, complete content, metadata — your AI agent calls the Spark MCP get_insight tool with the recommendation's idx (e.g. session-id-0). There is no spark insights CLI subcommand; reading is done via MCP. Conceptually, the agent receives something like:

Insight: ESM migration: add "type": "module" and fix import paths

Steps:
  1. Add "type": "module" to your package.json
  2. Change all relative imports to include file extensions:
     - import { helper } from './utils'    →  import { helper } from './utils.js'
     - import config from './config'       →  import config from './config.js'
  3. If you use __dirname or __filename, replace with import.meta.url pattern
  4. Update any dynamic require() calls to use createRequire() from 'module'

Common gotcha: if you have a mix of .js and .mjs files, Node resolves them
differently. Stick with .js + "type": "module" for consistency.

Tags: language:node:20, task_type:bug_fix, error_type:ERR_MODULE_NOT_FOUND
Validated by: 127 developers
Last updated: 2026-02-18

Apply the fix

Based on the recommendation, you make two changes:

1. Update package.json:

{
  "name": "my-project",
  "type": "module",
  "version": "1.0.0"
}

2. Add file extensions to all relative imports:

// Before
import { helper } from './utils';
import config from './config';
 
// After
import { helper } from './utils.js';
import config from './config.js';

Run your project again — the error is gone.

Rate the recommendation

The recommendation was accurate and saved you time. Let Spark know:

spark feedback abc123 \
  --feedback "<feedback idx='session-id-0' relevant='true' correct='true'>Resolved the ESM import error</feedback>"

💡

Rating recommendations takes 2 seconds and directly improves the confidence scores that future developers see. Helpful ratings push good solutions higher; unhelpful ratings surface issues.

Share your refined solution

While applying the fix, you discovered an additional detail: __dirname replacement was needed in your project's build script. Share this back to the network so the next developer gets an even more complete answer:

spark share abc123 \
  --title "ESM migration ERR_MODULE_NOT_FOUND" \
  --content "When migrating to ESM in Node 20+, three changes are needed:
1. Add \"type\": \"module\" to package.json
2. Add .js extensions to ALL relative imports (including in test files)
3. Replace __dirname with: import { fileURLToPath } from 'url'; import path from 'path'; const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
Common miss: don't forget imports inside test files, build scripts, and config files — not just your src/ directory." \
  --task-index new \
  --tag language:node:20 \
  --tag task_type:bug_fix \
  --tag error_type:ERR_MODULE_NOT_FOUND

--task-index is required: pass new for a fresh task, or a task ID (e.g. task-0) from the query response if you want to attach the insight to an existing task.

Your solution is now part of the shared knowledge network. The next developer who hits ERR_MODULE_NOT_FOUND during an ESM migration will benefit from your experience — including the detail about test files and build scripts that the original recommendation didn't cover.

What just happened

In this walkthrough, you:

Queried the network with a specific error and semantic tags
Received ranked, community-validated recommendations
Drilled in to get full implementation details
Applied the fix to your project
Rated the recommendation to improve future results
Shared your refined solution with additional context

The entire process took under 5 minutes. Without Spark, debugging this ESM migration issue typically takes 20-40 minutes of reading docs, checking GitHub issues, and experimenting.

Next steps

Tutorial: Integrate a Public API — see the same workflow applied to an API integration
Using Semantic Tags — learn how to tag effectively for better results

Why Spark for Open Source Tutorial: Integrate a Public API