Error Command “dev” not found when running yarn run dev

by

Summary

A developer encountered a "dev" not found error when executing yarn run dev in a Node.js project. The root cause was an incorrectly formatted command in the package.json file, specifically an invalid character that broke the script definition. This is a common configuration error in Yarn environments where syntax validation is stricter than older versions.

Root Cause

The error stems from the scripts object in the package.json file. While the script key "dev" is correctly defined, the value contained an invisible or invalid character (likely a non-breaking space or encoding artifact) immediately following the colon.

Specific details:

  • File: package.json
  • Section: scripts
  • Invalid Code: "dev": "nodemon server.js" (with hidden invalid whitespace)

Why This Happens in Real Systems

In modern JavaScript development, package managers like Yarn (v2+) and npm (v7+) have stricter parsing rules than earlier versions.

  1. Hidden Characters: Copy-pasting code from documentation, chat applications, or rich-text editors often introduces invisible Unicode characters (like \u00A0) that look like spaces but are not treated as such by the JSON parser or shell argument processor.
  2. Editor Limitations: Standard text editors often do not display these characters by default, making them “ghost bugs” that are invisible during code review.
  3. JSON Spec Strictness: The JSON standard requires specific whitespace characters. While some parsers are lenient, Yarn’s dependency resolver validates these strictly, causing the script resolution to fail.

Real-World Impact

  • Blocked Development: Developers cannot start local development servers, halting all feature work and debugging.
  • Frustration & Time Loss: Diagnosing this takes significant time because visual inspection of package.json reveals no obvious syntax errors.
  • CI/CD Failure: If a build pipeline relies on yarn install or yarn run commands, hidden characters can cause silent failures or cryptic errors in containerized environments (e.g., Docker), where environment differences exacerbate parsing issues.
  • Team Inconsistency: One developer’s environment might mask the issue, while another’s (especially on different operating systems) fails immediately, leading to “works on my machine” conflicts.

Example or Code

To resolve this, the package.json scripts section must be sanitized.

Incorrect (Conceptual – Hidden Character Present):
The following snippet appears correct but fails due to invisible non-breaking spaces around the colon or value.

{
  "scripts": {
    "dev": "nodemon server.js"
  }
}

Correct (Standardized):
Ensure plain ASCII spaces and proper JSON structure.

{
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js"
  }
}

Verification Code:
If you suspect hidden characters, you can inspect the string lengths or codes using a simple Node script:

const pkg = require('./package.json');
const devScript = pkg.scripts.dev;
// Log character codes to identify non-ASCII spaces
console.log([...devScript].map(c => c.charCodeAt(0)));

How Senior Engineers Fix It

Senior engineers approach this with a systematic “clean room” rebuild of the configuration to eliminate environmental variables.

  1. Re-type, Don’t Paste: Manually retype the script line ("dev": "nodemon server.js") rather than copying it. This ensures only standard ASCII characters are used.
  2. JSON Validation: Run a linter (like Prettier or ESLint) over the package.json file. Linters will often normalize whitespace and syntax, stripping out invalid hidden characters.
  3. Use npm pkg or yarn config: Instead of editing the file manually, use the CLI to set the script, which handles encoding automatically: 
    npm pkg set scripts.dev="nodemon server.js"
# or
yarn config set scripts.dev "nodemon server.js"
  4. Environment Check: Verify the Node.js and Yarn versions match the project requirements, as version mismatches can alter parsing behavior.

Why Juniors Miss It

Junior developers often lack the experience to identify invisible bugs.

  1. Assumption of Syntax: They assume that if the code looks right (e.g., "dev": "nodemon server.js"), it is right. They focus on logic errors rather than configuration formatting.
  2. Over-reliance on Copy-Paste: Inexperienced devs often copy commands from tutorials or StackOverflow without realizing that web formats can introduce non-breaking spaces.
  3. Lack of Tooling Knowledge: Juniors may not be using linters or formatters (like Prettier) that automatically fix these whitespace inconsistencies in package.json.
  4. Symptom Focus: They focus on the error message (“not found”) as a missing file or dependency issue, rather than a syntax parsing error in the config file.