Module not found error when k6 fails to resolve a local import

Question

When running a k6 test that imports a local JavaScript module, the tool aborts with a “module not found” error before any virtual users start.

The goal is to understand exactly how k6’s ES‑module resolver determines the file location for relative imports, especially when the test is launched from a directory different from the test file or when symlinks are involved.

Constraints include the resolver’s reliance on the test entry point as the base, possible variations across operating systems, and the lack of explicit documentation on whether NODE_PATH or custom path aliases affect resolution.

Does k6 resolve imports relative to the test file’s directory or the current working directory? How does it behave with symlinked files or Windows‑style path separators? Is there a mechanism to inspect the resolved module graph before test execution?

Tasadduq Burney · Answer

k6 resolves relative imports (those starting with ./ or ../) relative to the directory of the file containing the import statement, not the current working directory (CWD) from which the k6 run command is executed.

Resolution Logic and Constraints
Because k6 uses a Go-based JavaScript runtime (goja) rather than Node.js, it implements a strict ES module resolution strategy. This leads to several common pitfalls that trigger "module not found" errors during the initialization phase:

Explicit Extensions: k6 requires explicit file extensions. An import like import { helper } from './utils'; will fail; it must be import { helper } from './utils.js';.
  No Node.js Resolution: k6 does not support NODE_PATH, package.json "main" fields, or automatic node_modules folder scanning.
  Path Separators: While k6 normalizes paths internally, relative imports should use standard URI-style forward slashes (/) regardless of whether the host OS is Windows or Linux.

Behavior with Symlinks and CWD
Since resolution is anchored to the test file's location, changing the directory from which you launch the test does not break internal relative imports. However, symlinks can introduce uncertainty: if a file is symlinked, the resolver may treat the link's location as the base directory rather than the physical target path, potentially breaking relative paths to sibling files in the target directory.

Verification Steps
To diagnose and verify your module graph, use the following approach:

Check Extensions: Ensure every local import statement ends in .js.
  Verify Pathing: If your structure is /tests/main.js and /tests/lib/helper.js, the import in main.js must be import './lib/helper.js';.
  Debug Initialization: Run your test with the --verbose flag. While k6 does not provide a standalone "module graph inspector," verbose logging provides more detail on the initialization failures occurring before VUs start.

Diagnostic Detail Needed: Are you using a build tool (like Webpack or Rollup) to bundle your scripts before running k6, or are you running the raw JavaScript files directly?

Module not found error when k6 fails to resolve a local import

1 answer

Resolution Logic and Constraints

Behavior with Symlinks and CWD

Verification Steps

Your perspective belongs here.

0 question comments