AppsWindsurf

AI-built project runs on your machine but not on the server

Everything works on your laptop. On the server it crashes or will not build. The usual causes are different versions, missing settings and file names with the wrong capital letters.

  • Difficulty: Medium
  • Time: 30 to 90 minutes
  • Updated October 28, 2026

Symptoms

  • The build fails on the server but not locally
  • Errors about missing modules or files
  • The app starts but crashes on some pages
  • It worked last week and nothing seems to have changed

Why it happens

Your computer and the server are two different environments. They may run different versions of Node or PHP, have different settings, and treat file names differently.

AI tools write code against whatever is on your machine. They do not know what the server looks like, so the gaps only show up at deploy time.

Try this first

  1. Match the Node version

    Check which version you use locally and tell the server to use the same one.

    node -v
# save it for the project
node -v > .nvmrc

  2. Commit the lock file

    Make sure package-lock.json, yarn.lock or pnpm-lock.yaml is saved in your repository, so the server installs the same package versions you have.

  3. Add the settings the server needs

    Every environment variable your app reads locally from a .env file must also be set on the server. The .env file itself should not be in git.

  4. Check capital letters in file names

    Windows and macOS often ignore the difference between Header.jsx and header.jsx. Linux servers do not. Make the import match the file name exactly.

    // File on disk: components/Header.jsx
import Header from './components/header' // fails on Linux
import Header from './components/Header' // works everywhere

  5. Read the server logs

    The build and runtime logs on your host usually name the exact file and line. Start with the first error.

When to stop and call a person

Call a person if the server needs a different setup than your laptop, like a database, background jobs or a reverse proxy, or if you want a deploy pipeline that tests the app before it goes live.

Request a repair crew

Questions people ask

Why does it say a module is missing when it is installed?

Often the package was installed globally on your computer or never saved to package.json. Install it in the project so it is listed there.

Should I use Docker?

It helps keep environments the same, but it adds setup. For small apps, matching versions and settings is usually enough.

Related fixes

Windsurf Easy

Windsurf Cascade keeps changing more than you asked

You ask Cascade for one small fix and it edits five files. Set rules, point it at the right file and save…