General Errors

This troubleshooting guide covers general errors you may encounter while installing or developing with Medusa and how to resolve them.

Resolve "Cannot find module X" Errors#

This error can occur while installing any of Medusa's projects (for example, Next.js Starter storefront). There is no specific cause to this error.

One way to resolve it is by removing the node_modules directory in the project and re-installing the dependencies:

Cannot Find Module @medusajs/utils#

If you encounter a TypeScript or build error like the following:

Terminal
❯Cannot find module '@medusajs/utils' or its corresponding type declarations

The package @medusajs/utils does not exist as a public package. Use @medusajs/framework/utils instead.

For example, replace:

Code
import { MedusaService } from "@medusajs/utils" // wrong

With:

Code
import { MedusaService } from "@medusajs/framework/utils" // correct

Common utilities and classes available from @medusajs/framework/utils include MedusaService, MedusaError, Modules, InjectManager, InjectTransactionManager, and MedusaContext.

TypeError During medusa build Config Loading#

If you encounter a TypeError like the following during medusa build or medusa start:

Terminal
❯TypeError: Cannot read properties of null (reading 'admin')❯    at ConfigManager.loadConfig

This error means one of the required top-level properties in your medusa-config.ts is null or has an incorrect value. The config loader expects an object to be exported, not null or undefined.

Check your medusa-config.ts and make sure:

1. The file exports a valid configuration object using defineConfig.
2. None of the required properties (projectConfig, admin, modules) are explicitly set to null.

A minimal valid configuration looks like:

medusa-config.ts
1import { loadEnv, defineConfig } from "@medusajs/framework/utils"2
3loadEnv(process.env.NODE_ENV || "development", process.cwd())4
5module.exports = defineConfig({6  projectConfig: {7    databaseUrl: process.env.DATABASE_URL,8    http: {9      storeCors: process.env.STORE_CORS!,10      adminCors: process.env.ADMIN_CORS!,11      authCors: process.env.AUTH_CORS!,12      jwtSecret: process.env.JWT_SECRET || "supersecret",13      cookieSecret:14        process.env.COOKIE_SECRET || "supersecret",15    },16  },17})

For the full list of available configuration options, refer to Configure Medusa.