Fix Missing Start Script Deployment Failed in Node

When you push a Node.js app to Render, Railway, or Vercel, the platform runs npm start to boot your server. If it fails with 'npm ERR! missing script: start,' you assume your package.json is broken. Usually it is not. The script exists. The problem is almost always your project root directory is misconfigured, or you have a typo in the deployment config.

What Is the "Missing Start Script" Error?

Deployment platforms execute npm start to launch your Node.js app. This command looks for a 'start' key in the 'scripts' object in your package.json file. If the key is not there, npm exits with: npm ERR! missing script: start. The platform reports this, your build fails, and your app stays offline.

Here's what a correct start script looks like:

{
  "scripts": {
    "start": "node server.js"
  }
}

If you see the error during deployment, your platform either cannot find this key, or it is running npm from the wrong directory, or you have a typo in the script name. The error message does not tell you which one. This is the design flaw that blocks people for hours.

Why This Error Message Blocks People for Hours

The 'missing script' wording is a trap. Developers grep their package.json, confirm 'start' is there, and assume the platform is broken. They post on Reddit. They wait. Meanwhile, the real problem--misconfigured root directory in the deployment platform--sits ignored because the error message did not point to it.

This is why the same question appears five times in Reddit's top results for this query. It is a credibility problem with how deployment platforms report the error, not with your code. The platform should say: 'Cannot find package.json in the root directory' or 'Scripts found, but running npm from /api instead of /'. Instead it says 'missing script.' That is the blocker.

The error message is technically accurate. But it points at the wrong suspect. A developer with a working app and a wrong root directory gets told they have a missing script. They don't. This misdirection wastes 30 minutes to 2 hours per occurrence.

Step 1: Verify Your package.json Has a Start Script

Before you dig into deployment logs, confirm your start script exists locally. Open your package.json and check for the 'scripts' object. For an Express server, it might look like this:

{
  "name": "my-app",
  "scripts": {
    "start": "node server.js",
    "dev": "node --watch server.js"
  }
}

For Next.js or Nuxt, the deployment platform expects a build step followed by start:

{
  "scripts": {
    "build": "next build",
    "start": "next start"
  }
}

The 'start' key is required. The value depends on your project. Common patterns:

• node index.js for vanilla Node
• node server.js for Express
• next start for Next.js
• nuxt start for Nuxt
• npm run build && node dist/index.js for TypeScript projects that compile to dist/

If the key is there and matches your entry file, proceed to the next step. If it is missing, add it now and redeploy. If you're not sure what the value should be, run npm start locally on your machine. Whatever command works there is the one to put in your package.json.

Step 2: The Real Culprits -- 4 Common Causes

Assuming your start script exists, the error usually stems from one of these four problems:

Wrong Directory: package.json in a Subfolder

Your package.json might live in /api, /server, or another subdirectory, but the deployment platform is looking for it in the repository root. The platform runs npm from /, finds no package.json, and reports 'missing script.' The script is not missing; the platform is looking in the wrong place.

Fix: Check your deployment platform's settings for 'Root Directory' or 'Base Directory.' It should point to the folder containing package.json. If your project is a monorepo with multiple package.json files, confirm the platform is building the right one.

On Render: Go to Settings > Root Directory. On Railway: Check the Environment tab for a ROOT_DIR variable or the deployment settings. On Vercel: Look in Settings > Root Directory. On Ship: The root directory defaults to the project root; confirm your package.json is there.

Misconfigured Startup Command

Some platforms (Railway, Render, Northflank) let you set a custom 'Start Command' separate from npm start. If you override it, you bypass the package.json script entirely. For example, if you set 'Start Command' to npm run server but your package.json only has a 'start' key, the platform fails.

Fix: Check your platform's deployment settings. Is there a field for 'Start Command' or 'Custom Start Command'? If yes, either delete it (so the platform uses npm start) or ensure it matches a script in your package.json. If in doubt, leave it blank.

Typo in the Script Name

You named your script 'dev' instead of 'start'. Or your start script references node server.js but the file is actually app.js. The platform cannot find it.

Fix: Open your package.json and search for the exact key. Run npm start locally to verify it works. If it fails locally, it will fail in deployment too. Check the spelling of your entry file. Common mistakes: server.js vs app.js, index.ts vs src/index.ts, or a missing file extension.

Monorepo or Build-Output Issues

In a monorepo (npm workspaces, Yarn, Turborepo), your build step might output files to a dist/ folder, and the deployment platform might be trying to run npm from dist/ instead of the root. Or your.gitignore might hide node_modules, and the platform cannot install dependencies.

Fix: Check if your platform supports Monorepo roots or build directories. Confirm dependencies are not gitignored. If you have a build step, ensure the output is correct and the start command references the built files, not the source files. For example, if your build compiles TypeScript to dist/, your start script should be node dist/index.js, not node src/index.ts.

Step 3: How to Read Your Deployment Logs

When a deployment fails, the platform shows logs. These logs are your debug tool. Here is where to look:

1. Find the logs. Most platforms have a 'Logs,' 'Build,' or 'Deploy' tab in their dashboard. Click it.

2. Search for the error. Look for 'missing script' or 'npm ERR!'. Read the lines before and after it. The platform might have written 'Scanning /api for package.json' or 'Root directory: /server'. This tells you if the platform is looking in the wrong place.

3. Look for 'npm install' output. If npm install failed, dependencies are missing, and npm start will fail even if the script exists. Search for 'ERR!' or 'WARN' in the install log. Common issues: out-of-date Node version, platform-specific dependency conflicts, or a missing.npmrc file.

4. Check the build step output. If your project has a build step (webpack, Next.js, Nuxt, TypeScript compiler), the logs show if it succeeded. If the build failed, the start script will not run. Search for 'build failed' or 'error TS'.

5. Confirm the working directory. Some logs print the current working directory when npm runs. If it says 'Working directory: /api' and your package.json is in /, you found the problem. Look for lines like 'cd /' or 'current working directory'.

Most platforms format logs differently. Render shows them in the dashboard under 'Logs.' Railway shows them in the 'Deployments' tab. Vercel prints them during the GitHub Actions build step. Northflank shows them in 'Build Logs.' Ship shows them in the deployment history with clear labels. The content is similar; you just have to know where to click.

Platform-Specific Diagnosis

If the above steps did not help, your platform might have quirks. Here is a quick check for each:

Render

Root directory is set in the 'Settings' tab. Look for 'Root Directory' and confirm it matches. Render prints the full npm output, so search the logs for 'found in' or 'ENOENT' to see what npm could not locate. Also check Environment > Environment Variables to confirm no PATH or NODE_ENV issues.

Railway

Similar to Render. Check the 'Settings' or 'Variables' tab for 'Root Directory.' Railway also supports custom start commands via 'Start Command' field. If set, it overrides package.json. If you're seeing 'missing script' errors, clear this field and let Railway use the default npm start.

Vercel

Assumes the root directory is /. If your package.json is in a subfolder, set 'Root Directory' in Settings. Vercel also builds Next.js projects automatically; confirm your next.config.js is in the root, not a subfolder. Vercel's logs are terse; look for 'Build failed' and read backward.

Northflank

Known for sparse error messages. Check 'Deployment Logs' carefully. Northflank supports multiple 'Build Packs' (buildpacks). If you have the wrong pack selected, npm might not run at all. Confirm the build pack is 'Node.js' and the start command matches your package.json script. Northflank also does not auto-detect monorepos; you must set the root directory explicitly.

Ship

Offers simpler error reporting. If you see 'missing script,' check your package.json and root directory. Ship's logs are verbose and labeled; scroll to the 'npm start' line and read backward to find the real issue. Ship also lets you test your build locally via their CLI before deploying, which can catch these errors early.

When to Move to Managed Hosting

If you've debugged this error three times and it keeps coming back, the problem is not your code. It is your deployment platform's opaque error messages and configuration friction. Render, Railway, and Vercel are fine for most projects, but they all require you to understand their root-directory semantics and log formats. If that cognitive load feels wasted, there is an alternative.

Managed hosting platforms like Ship handle this differently. Ship's deployment model is simpler: you push code, Ship builds and runs it, and if there is an error, the dashboard tells you exactly what went wrong in plain English. No 'missing script' red herring. No digging through logs. The catch is that Ship is more opinionated; it works best if your project follows Node conventions (package.json in the root, standard start script). But for 80% of projects, that is fine.

Ship charges a flat monthly rate for unlimited deployments and straightforward compute pricing. This beats the penny-pinching of free-tier deployments on other platforms, which often leads to rushed debugging and frustration. You pay a bit more; you lose an entire class of problems. Hetzner with Coolify is cheaper on raw cost, but Ship wins on simplicity and debugging speed.

Frequently Asked Questions

What does "missing script: start" mean?

It means npm tried to run your 'start' script but could not find it in package.json. Usually the script exists and the platform is looking in the wrong directory.

How do I fix npm ERR! missing script: start?

Add a 'start' script to your package.json if missing. If it exists, check your deployment platform's root-directory setting and logs to confirm it is looking in the right place. Nine times out of ten, it is a directory issue, not a missing script.

Where do I add the start script in package.json?

In the 'scripts' object: "start": "node server.js" or similar, depending on your entry file and framework. The key must be exactly 'start' (lowercase).

Why does the error say "missing script" when the script is there?

Because the platform is running npm from the wrong directory (e.g., /api instead of /) and cannot see your package.json. The error message is technically correct but misleading. Your script is not missing; it is just not visible from where npm is looking.

What is the start script, and why does deployment need it?

The start script tells your platform how to boot your app. When you deploy, the platform runs npm start, which executes the command in your start script (e.g., node server.js). Without it, the platform does not know how to run your app.

How do I know if my package.json is in the right directory?

Your deployment platform should show you the root directory it is using. Check 'Settings' or look in the logs for the working directory when npm runs. It should match the folder containing your package.json. If you cloned your repo to /, then /package.json should match the platform's root. If you cloned it to /app-api, then the platform's root should be /app-api.

Does every Node.js project need a start script?

Yes. If you deploy to a platform that runs npm start, your package.json must have a 'start' key. If you use a custom start command, you can skip it, but this is rare and not recommended.

How do I run npm start if the start script is missing?

Do not. Add it to your package.json first. If you want to test the command locally, run the command directly (e.g., node server.js), but deployment platforms expect npm start to be defined. Without it, the platform fails.

The Bottom Line

The 'missing script' error during deployment is rarely about a missing script. It is almost always your project root directory being misconfigured in the deployment platform, or a typo in the script name, or dependencies not installing. Verify your package.json has a start script, check your platform's root-directory setting, read the logs for clues, and confirm the command matches your entry file.

If you find yourself debugging this error repeatedly across projects, it is a sign that your deployment platform's error messages are working against you. Managed hosting like Ship eliminates this entire class of problem by using simpler configuration and clearer diagnostics. You trade raw price (Hetzner with Coolify is cheaper; Ship is not) for peace of mind and faster deployments. For most teams that is the right trade.