Fix Cannot find module 'knex' Error

Seeing the error "Cannot find module 'knex'" is a common frustration for Node.js developers. This usually happens when your project cannot locate the Knex SQL query builder library. Don't worry. This guide will help you fix it fast.

We will cover the main causes, step-by-step solutions, and best practices to avoid this error in the future. Whether you are a beginner or experienced, these tips will get your project running again.

What Does This Error Mean?

Node.js uses require('knex') to load the Knex module. When the module is missing or not installed correctly, Node throws the error: Cannot find module 'knex'. This stops your application from starting.

Common reasons include: Knex not installed, wrong directory, missing node_modules folder, or a corrupted package.json file.

Quick Fix: Reinstall Knex

The simplest solution is to reinstall Knex. First, delete your node_modules folder and package-lock.json file. Then run the install command again.

# Delete node_modules and lock file
rm -rf node_modules package-lock.json

# Install Knex and its peer dependency
npm install knex --save

This ensures a fresh, clean installation. After that, try running your app again.

Check Your Working Directory

Make sure you are in the correct project folder. If you run your script from a different directory, Node cannot find the module. Use the terminal to navigate to your project root.

# Check current directory
pwd

# Navigate to your project folder
cd /path/to/your/project

Then run your script again. This is a simple but common mistake.

Verify Installation in package.json

Open your package.json file. Look for knex under dependencies or devDependencies. If it is missing, you need to install it.

{
  "dependencies": {
    "knex": "^2.5.0",
    "pg": "^8.11.0"  // Example database driver
  }
}

If Knex is listed but you still get the error, try running npm install again to sync the modules.

Install Missing Peer Dependencies

Knex requires a database driver like pg (PostgreSQL), mysql2, or sqlite3. If the driver is missing, Knex may fail to load. Install the appropriate driver for your database.

# For PostgreSQL
npm install pg --save

# For MySQL
npm install mysql2 --save

# For SQLite
npm install sqlite3 --save

After installing the driver, test your code again.

Global vs Local Installation

If you installed Knex globally with npm install -g knex, your local project may not find it. Node.js looks in the local node_modules folder first. Install Knex locally to fix this.

# Remove global Knex if needed
npm uninstall -g knex

# Install locally
npm install knex --save

Always prefer local installations for project-specific dependencies.

Check Node.js and npm Versions

Outdated Node.js or npm can cause module resolution issues. Update them to the latest stable versions.

# Check versions
node --version
npm --version

# Update npm
npm install -g npm@latest

Then reinstall Knex and test your application.

Use a Clear Cache

Sometimes npm cache is corrupted. Clear it and reinstall.

npm cache clean --force
npm install

This often resolves mysterious module errors.

Example: Working Knex Setup

Here is a minimal example that should work after fixing the error.

// app.js
const knex = require('knex')({
  client: 'pg',
  connection: {
    host: 'localhost',
    port: 5432,
    user: 'your_user',
    password: 'your_password',
    database: 'your_db'
  }
});

// Test connection
knex.raw('SELECT 1')
  .then(result => {
    console.log('Knex connected successfully');
  })
  .catch(err => {
    console.error('Connection error:', err);
  });

Run it with node app.js. If you see "Knex connected successfully", the error is fixed.

Prevent This Error in Future

To avoid the "Cannot find module 'knex'" error again, follow these tips:

• Always install dependencies inside your project folder.
• Use npm install after cloning a repository.
• Keep your package.json up to date.
• Consider using a .nvmrc file to manage Node versions.

If you encounter similar issues with other packages, check our guide on Fix Node.js Error: Cannot find module for general solutions.

Conclusion

The "Cannot find module 'knex'" error is usually easy to fix. Reinstall Knex locally, check your directory, and ensure database drivers are present. By following the steps in this article, you can resolve the error quickly and keep your project moving forward.

Remember to always install dependencies in the correct folder and keep your Node.js environment clean. Happy coding!