Cannot Find Module ‘dotenv’ — Node.js Error Explained & Fixed

When working with Node.js, using environment variables is a standard and secure way to manage sensitive configurations like API keys, database credentials, or tokens. The dotenv package is the most commonly used tool for this purpose. But if you’re here, you’ve probably run into a frustrating error that looks like this:

javascript

Error: Cannot find module 'dotenv'

This guide will explain what causes this error, how to fix it step-by-step, and give you additional tips to prevent it in the future. Let’s break it down!

What is the dotenv Module?

The dotenv module is a zero-dependency Node.js package that loads environment variables from a .env file into process.env. It helps you avoid hardcoding secrets in your codebase.

Here’s a basic example of how it’s used:

javascript

require('dotenv').config();

const apiKey = process.env.API_KEY;
console.log(apiKey);

This allows you to store your secrets in a .env file like so:

ini

API_KEY=123456789abcdef

But when the module isn’t installed correctly, or is missing, Node.js can’t find it—hence the “Cannot find module” error.

Why This Error Happens

Here are the most common reasons you might see this error:

1. The dotenv package is not installed
2. You’re running Node.js in the wrong directory
3. node_modules folder is missing or incomplete
4. dotenv is listed in devDependencies, but you’re in production
5. Typo in your require/import statement

Let’s go through how to fix each of these.

How to Fix “Cannot Find Module ‘dotenv'”

✅ 1. Install the dotenv Package

If you haven’t installed dotenv yet, or are unsure, the first step is to add it to your project using npm or yarn.

bash

npm install dotenv

Or, if you prefer yarn:

bash

yarn add dotenv

After installation, check your package.json file to make sure it appears under dependencies:

json

"dependencies": {
  "dotenv": "^16.0.3"
}

If it’s listed only under devDependencies, and you’re in a production environment, move it to dependencies.

✅ 2. Check Your Project Directory

Make sure you’re running your Node.js application in the root folder of your project—the same one where your node_modules and package.json files live.

For example, if your structure looks like this:

pgsql

my-app/
├── node_modules/
├── .env
├── index.js
└── package.json

You should be running:

bash

node index.js

Not from a subdirectory like:

bash

cd src && node index.js

Unless you’ve properly handled path references, this can lead to module resolution errors.

✅ 3. Delete and Reinstall node_modules

Sometimes, the node_modules directory gets corrupted or incomplete—especially if you cloned a repository without running npm install.

Try this:

bash

rm -rf node_modules package-lock.json
npm install

This will delete the existing dependencies and reinstall everything cleanly.

✅ 4. Double Check Your Import Syntax

Make sure your require or import statement is written correctly. These are the valid formats:

javascript

require('dotenv').config();

Or if you’re using ES Modules (with "type": "module" in package.json):

javascript

import dotenv from 'dotenv';
dotenv.config();

A typo like require('dotnev') or require('dot.env') can also throw this error.

✅ 5. Avoid Global Installation

Installing dotenv globally using -g won’t help. Node.js does not look for globally installed modules when running a local project.

Bad:

bash

npm install -g dotenv

Always install it as a local dependency inside your project.

Still Not Working? Try This Checklist

If the error persists, here’s a quick checklist to walk through:

• Did you run npm install dotenv?
• Are you in the correct project directory?
• Does your package.json include "dotenv" in dependencies?
• Is there a typo in the require() or import statement?
• Did you restart your dev server after installing?

How to Prevent This in the Future

To avoid this error down the line, consider the following best practices:

💡 Use .env.example Files

Include a .env.example file in your repo (with fake values or keys) so that other developers know which variables they need to set.

text

API_KEY=your_api_key_here
DB_URL=your_database_url_here

💡 Add dotenv to All Environments

If your code relies on environment variables in all environments (not just during development), make sure dotenv is listed in your dependencies, not devDependencies.

💡 Add .env to .gitignore

Never commit your real .env file. Add this line to your .gitignore:

bash

.env

This helps protect sensitive data from accidentally being pushed to public repos.

Conclusion

The “Cannot find module ‘dotenv’” error is a common issue when starting with Node.js or managing dependencies across multiple machines or environments. The fix is usually simple—install the package locally using npm install dotenv, and make sure your setup is clean and consistent.

By following the steps above, you’ll not only solve the error but also set up your environment in a more maintainable and secure way. And the next time you see this error, you’ll know exactly what to do.