PhantomJS Cannot Find Module: Fix PATH and Installation Errors

“Cannot find module” and “PhantomJS not found on PATH” are different errors. The first usually means Node.js cannot resolve a package or file from the code that requested it. The second means a process could not locate the PhantomJS executable through its environment. An npm installation can also fail while loading its own script or a nested dependency, which is a third case.

Start with the exact missing name and the first relevant stack frame. Those usually identify which layer failed and which fix to try.

1. Identify which lookup failed

Error text or context	Likely failure	First check
Cannot find module 'phantomjs-prebuilt' in application output	Node package resolution	Is the package installed in the project the application is running from?
Cannot find module 'throttleit' during npm install	An install-time transitive dependency	Which package and file appear in the stack trace?
Cannot find module './install.js' or another installer file	Installer script loading or environment issue	Capture the complete npm output and environment versions.
PhantomJS not found on PATH	Executable lookup, possibly only a warning	Read subsequent log lines and verify the binary path used by the calling process.

Node’s CommonJS resolver searches for modules relative to the requiring module, checking nearby and parent node_modules directories. A global package installation in an unrelated location does not necessarily satisfy a project’s require(). See the [Node.js module resolution documentation](https://nodejs.org/api/modules.html) and [npm’s guide to using packages in a project](https://docs.npmjs.com/using-npm-packages-in-your-projects/).

2. Fix a missing application dependency

1. Change to the application’s project directory, the one containing its package.json.
2. Check the error’s missing identifier and the code or package that requires it.
3. Install the required package in that project, if it is a dependency your application actually needs.
4. Run the app again from the same project context.

# From the project directory, add the package your code requires
npm install phantomjs-prebuilt

# Inspect whether the project has it installed
npm ls phantomjs-prebuilt

# Run the application from this project
node app.js

If the exact missing name is different, such as some-library, install and declare that package instead of blindly installing phantomjs-prebuilt. npm documents project dependencies and package installation in its [project package guide](https://docs.npmjs.com/using-npm-packages-in-your-projects/).

Check the working directory

In monorepos, containers, task runners, and IDE launch configurations, the process may start in a different directory from your terminal. Compare the current directory and package manifest for both invocations:

pwd
node -p "process.cwd()"
node -p "require.resolve('phantomjs-prebuilt')"

The last command either prints the resolved entry point or gives a module resolution error. Run it from the same directory and environment as the failing application.

3. Fix an executable PATH problem

PATH is an environment variable used to find executable programs. It is separate from Node’s search for JavaScript modules. A package can exist under node_modules while a process still cannot find the executable it expects, or the installer can print a PATH warning and then set up a package-local binary successfully.

1. Read the full install log, including lines after the PATH message.
2. Find the actual PhantomJS binary location reported by the installer, if any.
3. Check whether that file exists and is executable.
4. Inspect the PATH inherited by the process that launches the app. Shell, IDE, service, and CI environments can differ.
5. If the package provides a local executable, invoke that project-local executable or configure the caller with its path according to that package’s documentation.

# Unix-like shell: inspect the environment and lookup
printf '%s\n' "$PATH"
command -v phantomjs

# Windows Command Prompt
where phantomjs

# Windows PowerShell
Get-Command phantomjs

Do not treat the phrase “PhantomJS not found on PATH” as proof that installation failed. A historical installation log printed that message before extracting a binary into the project’s node_modules/phantomjs-prebuilt tree. Check the rest of the log and the executable path actually used. [The historical report](https://github.com/SharePoint/sp-dev-gdpr-activity-hub/issues/43) is an example, not a guarantee that every install behaves the same way.

4. Diagnose errors that happen during npm install

An error emitted while npm is installing a package may not be the same as an application-level require() failure. Find the first Cannot find module line and inspect the stack frames immediately below it. They show which script attempted the missing import.

• If the stack points to the package’s install.js, the install script itself could not be loaded or executed.
• If it points to a nested module such as throttleit under another package, the missing item is a transitive dependency, not necessarily phantomjs-prebuilt.
• If the log later reports successful binary extraction, the earlier PATH line may have been a warning followed by a fallback.

Historical PhantomJS issue reports describe Windows install-script loading trouble and a missing nested dependency. Their authors discussed possible npm or environment problems, but those reports do not establish the cause on a different machine. See [issue #302](https://github.com/Medium/phantomjs/issues/302) and [issue #599](https://github.com/Medium/phantomjs/issues/599). Record the full output and environment before applying a workaround.

Capture the details that make an install failure diagnosable

node --version
npm --version
npm config get registry
pwd
npm install --verbose

On Windows, record the equivalent current directory and the exact shell used. Include the complete error and stack, operating system, Node and npm versions, command, and project directory when searching issue trackers or asking for help. Avoid deleting lockfiles or forcing old dependencies as a first response: that changes the dependency graph and may obscure the original cause.

5. Troubleshooting checklist

Symptom	Cause to check	Action
App cannot find phantomjs-prebuilt	Not installed in the app’s project, or app runs from another project directory	Install it in the correct project and verify with npm ls and require.resolve().
App cannot find a different package name	The requiring code expects a dependency absent from this project	Check spelling and install the named dependency in the project that runs the code.
Install fails with missing nested module	A transitive install dependency could not be loaded	Use the stack to identify the parent package; preserve logs and versions before changing dependencies.
Install says PhantomJS is not on PATH	The executable is not globally discoverable, or the message is an intermediate warning	Read following lines and verify the package-local executable and caller environment.
Works in terminal, fails in IDE or service	The process has a different working directory or environment	Compare process.cwd(), PATH, Node version, and dependency installation in both contexts.
Works on one machine, fails on another	Different runtime, platform, lockfile install, or environment	Capture versions and install output; reproduce from the project’s declared dependencies.

Or skip the browser setup

If your task is to capture a website rather than maintain a PhantomJS installation, [ScreenshotNeo](https://screenshotneo.com) returns a screenshot or PDF from one API request. See the [API documentation](https://screenshotneo.com/docs/) for options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

• Cookie and consent banners are accepted and removed before capture; known newsletter popups and chat widgets are also removed.
• Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Response headers report the page verdict and billing status.
• An MCP server lets AI agents use screenshot, page information, and PDF capture tools.
• The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up free for 1,000 screenshots a month, no card required.

Performance, reliability, and cost notes

• Performance: A missing module or executable is a setup failure; repeatedly rerunning the same command without inspecting the stack will not identify the failing lookup. Resolve packages from the project environment and verify the executable from the actual caller.
• Reliability: Lockfiles and consistent Node/npm versions help keep installs repeatable, but historical issue reports are tied to their original software versions. They are clues, not current compatibility guarantees.
• Cost: PhantomJS package installation itself does not explain the cost of your hosting or maintenance. If you switch to a screenshot API, account for capture volume and plan limits; ScreenshotNeo’s stated plans range from free 1,000 monthly shots through paid tiers, with every feature on every plan.

Frequently asked questions

Does installing PhantomJS globally fix “Cannot find module”?

Usually not when application code cannot resolve a Node package. Install the dependency in the project environment used by the app. A global executable and a project-local JavaScript module are separate lookups.

Is “PhantomJS not found on PATH” always fatal?

No. Inspect the complete log: some installers may report the lookup failure and then configure a binary locally. Verify the final outcome and path rather than relying on one line.

Should I keep using phantomjs-prebuilt?

This error alone cannot answer that. It identifies a resolution or installation problem, not whether the package fits your current runtime or project. The cited issue reports are historical and do not establish present-day compatibility.

What should I include when asking for help?

Provide the exact command, full stack trace, operating system, Node and npm versions, project directory, and whether the error occurred during installation or while running the application.