Fix Cannot Find Module 'agenda' Error

Encountering the error "Cannot find module 'agenda'" in Node.js can stop your project right away. This error means your code cannot locate the agenda package. Agenda is a popular job scheduling library for Node.js. This guide will help you fix the error quickly and prevent it from happening again.

We will cover common causes and solutions. You will learn how to install, verify, and correctly import the agenda module. Let's start by understanding why this error occurs.

What Causes the "Cannot find module 'agenda'" Error?

This error usually happens because the agenda package is not installed in your project. It can also occur if you are running the code from the wrong directory. Other reasons include a corrupted node_modules folder or an outdated package version.

The error message looks like this in your terminal:

Error: Cannot find module 'agenda'
Require stack:
- /home/user/project/app.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> (/home/user/project/app.js:1:1)

This output clearly shows that Node.js tried to load 'agenda' from your project but could not find it. The stack trace points to the exact file and line number where the require call failed.

Step 1: Install the Agenda Package

The most common fix is to install agenda using npm or yarn. Run this command in your project root directory:

npm install agenda

If you use yarn, use this command instead:

yarn add agenda

After installation, check your package.json file. You should see agenda listed under dependencies. This confirms the package is now available for your project.

Step 2: Verify the Installation

To confirm that agenda is installed correctly, run the following command in your terminal:

npm list agenda

You should see output similar to this:

your-project@1.0.0 /path/to/project
└── agenda@5.0.0

If you see the version number, the package is installed. If you see "(empty)" or an error, try reinstalling.

Step 3: Check Your Import Statement

Make sure you import agenda correctly in your code. Use require or import syntax properly. Here is an example using require:

// Correct way to require agenda
const Agenda = require('agenda');

If you use ES modules, write it like this:

// For ES modules
import Agenda from 'agenda';

Double-check that the module name is spelled exactly as 'agenda' (all lowercase). A typo like "Agenda" or "agenda" with a capital letter will cause the error.

Step 4: Run from the Correct Directory

The error often occurs when you run your script from a folder that does not contain the node_modules directory. Always run your Node.js script from the project root. For example:

cd /path/to/your/project
node app.js

If you are inside a subfolder, Node.js will not find agenda. Use the full path or change directory first.

Step 5: Reinstall node_modules

Sometimes the node_modules folder gets corrupted. Delete it and reinstall all dependencies. Run these commands:

rm -rf node_modules
npm install

This will remove the old folder and create a fresh one with all packages, including agenda.

Step 6: Check Package Version Compatibility

Agenda may require a specific Node.js version. Check the agenda documentation for compatibility. If you have an older Node.js version, upgrade it. Use node -v to see your current version. Then update Node.js to the latest LTS release.

You can also check if the installed agenda version is correct. Run npm view agenda version to see the latest version. Then update if needed:

npm update agenda

Step 7: Use a Global Install (Not Recommended)

Avoid installing agenda globally. Global installs can cause conflicts and are not project-specific. Always install it as a local dependency. If you accidentally installed it globally, uninstall it first:

npm uninstall -g agenda

Then install it locally as shown in Step 1.

Example: Simple Agenda Job

Here is a complete example to test your setup. Create a file named test-agenda.js with this code:

// Import agenda
const Agenda = require('agenda');

// Define MongoDB connection string (use your own)
const mongoConnectionString = 'mongodb://127.0.0.1/agenda-example';

// Create a new Agenda instance
const agenda = new Agenda({ db: { address: mongoConnectionString } });

// Define a job
agenda.define('send email', async job => {
  const { to } = job.attrs.data;
  console.log(`Sending email to ${to}`);
});

// Start agenda and schedule a job
(async function() {
  await agenda.start();
  await agenda.schedule('in 10 seconds', 'send email', { to: 'user@example.com' });
  console.log('Job scheduled');
})();

Run the file with this command:

node test-agenda.js

If agenda is installed correctly, you will see output like:

Job scheduled
Sending email to user@example.com

This confirms that agenda is working. If you still see the error, double-check the steps above.

Additional Tips

Always keep your package.json and package-lock.json files in version control. This ensures other developers can install the exact same dependencies.

If you are using a monorepo or workspace, make sure agenda is installed in the correct package. Run npm install from the workspace root or the specific package folder.

For more help with similar errors, check out this guide on how to Fix Node.js Error: Cannot find module. It covers general troubleshooting for missing modules.

Conclusion

The "Cannot find module 'agenda'" error is easy to fix. Start by installing the package with npm install agenda. Verify the installation, check your import statement, and run your script from the correct directory. If problems persist, reinstall node_modules or update your Node.js version. With these steps, you can get back to building your job scheduler quickly.