Node ESM scratch script cannot find the project's packages

Agent diagnostic brief

Exact symptom

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'yaml' imported from <scratch-dir>/check.mjs

Where it has been observed

Node.js 26 with a pnpm workspace; ESM helper scripts written outside the project tree.

Likely distinct causes

The script lives outside the project tree.
The package is not installed: check resolution from the project root.
The package's exports do not allow the requested entry point: the error message differs.

How to distinguish them

Run a copy of the same script placed inside the project: if it works, location is the cause.
Resolve the package from the project root with import.meta.resolve.
Read the 'imported from' path in the error.

Current approaches

Run throwaway ESM scripts from inside the project tree (solution-node-esm-scratch-dir-resolution, revision 1).

Known obsolete approaches

Relying on the current working directory for ESM resolution.

Versions and freshness

Observed 2026-08-12..18 with Node 26.0.0; reproduced 2026-09-11
Editorial and primary-source review date: 2026-09-11.

What remains unknown

Behavior with import maps or custom loaders.
Independent reproduction by a different operator has not been established.

Deeper evidence

Problem

Node ESM scratch script cannot find the project's packages

Observed symptom

A one-off helper script written in the agent's scratch directory fails to import a package (or a relative project module) that the project has installed, because Node resolves imports from the script's own location, not the current working directory.
This historical observation is same-operator evidence and does not establish prevalence.

Operator goal

Run a quick validation script that imports the project's dependencies.

Current understanding

Node's ESM resolver searches node_modules folders starting from the importing file's directory and walking upward, and resolves relative specifiers against the importing file's URL, not the current working directory.

Known limitations

Workspace managers with custom linking can add their own resolution rules.

Known negative results

Use a relative import from a script placed directly in a temporary directory. Result: Node resolved it against the temporary directory and suggested the real path. Why it misleads: Relative specifiers resolve against the importing file's URL.
No same-operator execution in this release counts as an independent reproduction.

Primary and recurrence sources

Node.js ECMAScript modules
Primary · Primary documentation · Date not supplied · Reviewed 2026-09-11 · Rights: allowed_to_summarize
Current primary material reviewed for claude-historical-corpus-1: Node.js ECMAScript modules.

Rights and provenance

Origin

Based on a real operator execution; identifying project details removed.

Rights

State: allowed_to_summarize
Review basis: Owner-authorized factual synthesis of the operator's own Claude-assisted execution, independently written from reviewed current primary sources; no transcript expression is published.

Editorial review date

2026-09-11

Known approaches

solution · Revision 1

Run throwaway ESM scripts from inside the project tree

Production corpus importer · 2026-09-11T20:00:00.000Z
Operator Knowledge for Agents editorial · Historical operator record · Digital source: trainedAlgorithmicMedia · Rights: owned

## Candidate action - Run throwaway ESM scripts from inside the project tree. Place throwaway ESM scripts inside the project tree (and remove them afterwards) or import by absolute file URL; do not expect bare specifiers to resolve from an unrelated directory. This is a candidate procedure supported by same-operator executions within the stated version boundary, not a universal fix. ## Applicability - Use when the observed signature is: Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'yaml' imported from <scratch-dir>/check.mjs. - Observed scope: Node.js 26 with a pnpm workspace; ESM helper scripts written outside the project tree. - Stop if the first failing stage or product boundary differs. ## Procedure - Write or copy the helper into the project directory as a temporary ignored file. - Run it, then delete it. - Alternatively import dependencies by absolute file URL. - Keep scratch directories for outputs, not for scripts that need project dependencies. ## Limitations - Workspace managers with custom linking can add their own resolution rules. ## Obsolete approaches - Relying on the current working directory for ESM resolution. ## Negative results - Use a relative import from a script placed directly in a temporary directory. Result: Node resolved it against the temporary directory and suggested the real path. Why it misleads: Relative specifiers resolve against the importing file's URL. - No external or same-operator report was promoted to independent reproduction credit. ## Evidence boundary - Grounded in current primary source records src-node-esm-current. - Grade A same-operator observation (2026-08-12..2026-08-18): Identical script content failed with ERR_MODULE_NOT_FOUND from the scratch directory and succeeded once placed inside the project tree, in two projects. - Only immutable manifest executions count as Knowledge for Agents Attempts or Outcomes. ## What remains unknown - Behavior with import maps or custom loaders. - Whether the approach works outside the stated environment remains unknown.

Candidate id

claude-node-esm-scratch-dir-resolution

Historical period

2026-08-12..2026-08-18

Historical date

2026-08-18

Verification grade

Operator relationship

same_operator

Independent reproduction

false

History source

same-operator Claude agent session history

Provenance disclosure

Based on a real operator execution; identifying project details removed.

Applicability

State

partial

Text

Applies when the failed stage matches: Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'yaml' imported from <scratch-dir>/check.mjs.

Facts

Component: ESM specifier resolution
Operation: run a helper script that imports project dependencies
Protocol: ECMAScript modules

Pack

Candidate action: Run throwaway ESM scripts from inside the project tree. Place throwaway ESM scripts inside the project tree (and remove them afterwards) or import by absolute file URL; do not expect bare specifiers to resolve from an unrelated directory. This is a candidate procedure supported by same-operator executions within the stated version boundary, not a universal fix.
Applicability: Use when the observed signature is: Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'yaml' imported from <scratch-dir>/check.mjs.
Observed scope: Node.js 26 with a pnpm workspace; ESM helper scripts written outside the project tree.
Stop if the first failing stage or product boundary differs.
Steps: Write or copy the helper into the project directory as a temporary ignored file.
Run it, then delete it.
Alternatively import dependencies by absolute file URL.
Keep scratch directories for outputs, not for scripts that need project dependencies.
Limitations: Workspace managers with custom linking can add their own resolution rules.
Obsolete approaches: Relying on the current working directory for ESM resolution.
Negative results: Use a relative import from a script placed directly in a temporary directory. Result: Node resolved it against the temporary directory and suggested the real path. Why it misleads: Relative specifiers resolve against the importing file's URL.
No external or same-operator report was promoted to independent reproduction credit.
Evidence boundary: Grounded in current primary source records src-node-esm-current.
Grade A same-operator observation (2026-08-12..2026-08-18): Identical script content failed with ERR_MODULE_NOT_FOUND from the scratch directory and succeeded once placed inside the project tree, in two projects.
Only immutable manifest executions count as Knowledge for Agents Attempts or Outcomes.
What remains unknown: Behavior with import maps or custom loaders.
Whether the approach works outside the stated environment remains unknown.

Rights

State: allowed_to_summarize
Review basis: Original diagnostic procedure synthesized from owner-authorized execution facts and linked current primary sources; no private source code, logs, or transcript expression is published.

Source ids

src-node-esm-current

Editorial review date

2026-09-11

Seo metadata

Meta title: Run throwaway ESM scripts from inside the project tree | Knowledge for Agents
Meta description: Candidate procedure for node esm scratch script cannot find the project's packages: applicability, steps, current sources, limitations, negative results, and unknowns.

Historical execution

Disclosure: Based on a real operator execution; identifying project details removed.
Operator relationship: same_operator
Independent reproduction: false

Problem id

problem-node-esm-scratch-dir-resolution

Page 1 · 1 children total

Sources and related records

No source relations recorded.