Troubleshooting

Wrong Node.js version (EBADENGINE)

You see:

npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: '[email protected]',
npm warn EBADENGINE   required: { node: '>=20.19.0' },
npm warn EBADENGINE   current: { node: 'v18.19.0', npm: '10.2.3' }
npm warn EBADENGINE }

Why: your Node.js is older than 20.19. Some packages need 20.19 or newer, so the app can fail later with strange errors.

Fix: install Node.js 22 LTS from nodejs.org (or nvm install 22). Close and open the terminal, check node -v, delete the node_modules folder, and run npm install again.

npm ci says the lock file is not in sync

You see:

npm error `npm ci` can only install packages when your package.json and package-lock.json
or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install`
before continuing.

Why: package.json was changed (for example, you added a package) but package-lock.json was not updated.

Fix: run npm install once. It updates package-lock.json. Then npm ci works again. Copy both files to your server together.

npm cannot find package.json (ENOENT)

You see:

npm error code ENOENT
npm error syscall open
npm error path /Users/you/Downloads/chatcart/package.json
npm error enoent Could not read package.json: Error: ENOENT: no such file or directory

Why: you are in the outer chatcart folder. The app is in the inner one.

Fix: cd chatcart once more, so you are in chatcart/chatcart. Check with ls or dir that you see package.json.

npm run seed says .env.local: not found

You see:

node: .env.local: not found

Why: npm run seed and npm run create-admin read .env.local, and the file is not in the app folder.

Fix: do step 6 of the quick start in the inner chatcart folder. On Windows, check that the file is not named .env.local.txt (turn on File name extensions in File Explorer to see it).

MONGODB_URI is not set

You see, in the terminal:

Error: MONGODB_URI is not set. Add it to your environment (e.g. .env.local) before using the database.

The storefront shows No store configured yet, and you cannot sign in.

Why: .env.local is missing, is in the wrong folder, or has no MONGODB_URI line.

Fix: add MONGODB_URI=... to .env.local in the app folder. Then stop the app with Ctrl + C and run npm run dev again. The startup lines must show Environments: .env.local.

JWT_SECRET is missing, too short, or still the sample value

You see, when you try to sign in:

Error: JWT_SECRET is missing or too short (min 16 chars). Set it in your environment (.env.local).

or:

Error: JWT_SECRET is still the sample value from .env.example. Replace it with your own long random string in .env.local.

The sample value is printed in a public file, so ChatCart refuses it. Anyone who knows it could sign in as any user.

Fix: set JWT_SECRET in .env.local to a random value of 32 characters or more (see step 6), then restart the app. If you change it later, everyone is signed out. That is normal.

Cannot connect to local MongoDB (ECONNREFUSED)

You see:

MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017

or connect ECONNREFUSED ::1:27017.

Why: MongoDB is not running, or the address is wrong. The ::1 version means localhost was turned into the IPv6 address.

Fix: start MongoDB (see Check that MongoDB is running). In MONGODB_URI, write 127.0.0.1 instead of localhost.

Atlas: your IP address is not allowed

You see:

MongooseServerSelectionError: Could not connect to any servers in your MongoDB Atlas cluster.
One common reason is that you're trying to access the database from an IP that isn't whitelisted.

Fix: in Atlas, open Network Access and add the IP address of the computer or server that runs ChatCart. Home internet addresses can change; if it worked yesterday, add your current IP again. Wait about a minute, then restart the app.

Atlas: bad auth, or special characters in the password

You see one of these:

MongoServerError: bad auth : authentication failed
MongoParseError: Password contains unescaped characters
URIError: URI malformed

Why: the username or password in MONGODB_URI is wrong, or the password has characters like @ : / ? # % that are not URL-encoded. It can also be the password of your Atlas website account instead of the database user.

Fix: use the database user from Database Access in Atlas. Encode special characters (see Special characters in the password), or edit the user and give it a password with only letters and numbers. Remove the < > signs around the password.

Atlas: querySrv ENOTFOUND

You see:

Error: querySrv ENOTFOUND _mongodb._tcp.cluster0.abcde.mongodb.net

Why: the cluster address has a typo, or your network cannot look up this kind of address (some office and mobile networks block it).

Fix: copy the connection string again from Atlas. If it still fails, try another network, or set your computer's DNS server to 8.8.8.8 or 1.1.1.1.

Port 3000 is already in use

With npm run dev, Next.js moves to another port and prints a warning like this:

⚠ Port 3000 is in use, using available port 3001 instead.

With npm run start, it stops:

Error: listen EADDRINUSE: address already in use :::3000

Fix: close the other program that uses port 3000 (often an older ChatCart still running in another terminal), or choose another port: npm run dev -- -p 3001 or npm run start -- -p 3001. If you change the port, update APP_URL too.

The demo login does not work

The sign-in page says:

Invalid email or password.

Why: the demo login [email protected] / ChangeMe123! only exists after npm run seed, and only when ADMIN_EMAIL and ADMIN_PASSWORD were empty. It does not exist after npm run create-admin.

Fix: run npm run seed (Path A), or sign in with the account you made with create-admin. Forgot the password? Run npm run create-admin -- --email [email protected] --password "NewPassword1" --reset-password.

The seed did not run

You see:

❌ This database already has ChatCart data, so the seed did not run.
   The seed deletes all stores, products, orders, users and customers,
   then loads the demo data. To do that anyway, run:

     npm run seed -- --force

Why: this protects a real shop from being wiped. It also happens if you ran create-admin first.

Fix: only if you are sure this database holds nothing you need, run npm run seed -- --force. Or point MONGODB_URI at a new database name, for example /chatcart-demo.

create-admin stops with a message

Sign-in does nothing on a server

After npm run build and npm run start, you sign in, no error appears, but you stay on the sign-in page.

Why: in production, the login cookie is only sent over HTTPS. Your browser drops it on a plain http:// address such as http://203.0.113.10:3000.

Fix: put the app behind HTTPS (Nginx or Caddy, see Deployment). On your own computer, use npm run dev or open http://localhost:3000.

The storefront says "No store configured yet"

Why: there is no active store, or the database cannot be reached. It is normal right after create-admin (Path B).

Fix: create a store in Admin, Stores and check that it is Active. If you already have stores, look in the terminal for a database error from this list.

WhatsApp opens the wrong number, or says the number is invalid

Why: the store still has a demo placeholder number (+15551234567 or +15557654321), or the number has no country code, or it starts with the local 0. Each store has its own number, so Aroma Café can still have the placeholder after you changed Bloom Boutique.

Fix: in Admin, Settings, General, set WhatsApp number for every store, in international format (for example +447700900123), and save. Or set SEED_WHATSAPP_NUMBER in .env.local and run npm run seed -- --force (this reloads the demo data).

Uploaded images show 404, or the upload fails

Images you upload are saved in UPLOAD_DIR (default: public/uploads in the app folder) and served by the app at /uploads/<file>. Common causes:

• Images are gone after a new deploy: the deploy replaced the app folder, and the uploads with it. Set UPLOAD_DIR to a folder outside the app, for example /var/chatcart/uploads, and restart.
• You changed UPLOAD_DIR: move the old files from the old folder into the new one.
• Your web server serves /uploads itself: remove any Nginx location /uploads rule, so the request reaches ChatCart.
• The upload says Could not save the upload: the app cannot write to the folder. Give the user that runs Node.js write access, for example sudo chown -R $USER /var/chatcart/uploads.
• Large images fail behind Nginx with 413 Request Entity Too Large: add client_max_body_size 6m; to your Nginx site. ChatCart accepts up to 5 MB.
• Serverless hosts (Vercel, Netlify) delete files between deploys. Use image URLs (HTTPS) there, or a VPS.

Changes do not show after next build

Why: npm run start serves the version you built. Changes to the code or to .env.local need a new build and a restart. Changes you make in the admin (products, settings, theme) show at once, with no rebuild.

Fix:

npm run build
pm2 restart chatcart      # or stop and run npm run start again

If you see Could not find a production build in the '.next' directory, you ran npm run start before npm run build. A logo or favicon that still looks old is usually the browser cache: press Ctrl + Shift + R (Cmd + Shift + R on a Mac).

npm run build fails to download fonts

You see an error like this:

Failed to fetch font `Inter`.

Why: during the build, Next.js downloads the fonts once and then serves them from your own server. The build machine needs internet access for that.

Fix: build on a machine with internet access, or allow access to fonts.googleapis.com and fonts.gstatic.com during the build. Your running store never contacts Google.

Windows-specific problems

• cp is not recognized: in Command Prompt use copy .env.example .env.local. In PowerShell use Copy-Item .env.example .env.local.
• npm.ps1 cannot be loaded because running scripts is disabled on this system: use Command Prompt instead of PowerShell, or run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once in PowerShell.
• node: bad option: --env-file=.env.local: the seed and create-admin scripts use tsx --env-file, which needs Node.js 20.6 or newer. ChatCart needs 20.19 or newer anyway. Update Node.js.
• The file is named .env.local.txt: Notepad adds .txt. In the save window, choose All files as the type, or rename the file with File Explorer extensions turned on.
• Very long paths: unzip close to the drive root, for example C:\sites\chatcart, to avoid path length errors.