Prettier Troubleshooting: AI-Optimized Knowledge Base

Critical Failure Modes and Solutions

Format-on-Save Failures

Primary Cause: Default formatter not set (90% of cases)
Nuclear Solution:

killall code
code --install-extension esbenp.prettier-vscode --force

Configuration Requirements:

• Editor: Default Formatter = Prettier - Code formatter
• Editor: Format On Save = ✅ Enabled

Secondary Cause: Rogue package.json in parent directories breaks HTML projects
Fix: Delete unnecessary package.json files above current folder

Syntax Error Failures

Root Causes (frequency order):

1. Missing semicolons with "semi": false config
2. Unclosed braces/brackets
3. Invalid JSX syntax mixing HTML and JS
4. ES6 modules mixed with CommonJS in same file

Debug Command: npx prettier --check filename.js - provides exact line number and error

File Type Detection Failures

Symptom: Format works sometimes, fails others
Cause: VS Code cannot identify file language
Immediate Fix: Click language indicator in bottom-right, select correct language
Permanent Fix:

{
  "files.associations": {
    "*.js": "javascript",
    "*.jsx": "javascriptreact",
    "*.ts": "typescript",
    "*.tsx": "typescriptreact"
  }
}

Performance Critical Issues

Speed Optimization (Prettier 3.6+)

Baseline Performance: 4+ minutes for large codebases
Optimized Performance: 18 seconds (25x improvement)

Fast CLI Configuration:

npx prettier --write . --cache

Rust Parser Installation:

npm install @prettier/plugin-oxc --save-dev

{
  "plugins": ["@prettier/plugin-oxc"]
}

Performance Thresholds:

• 50k+ lines: Requires Rust parser
• 10k+ lines: Causes VS Code memory issues
• 1000+ spans: Breaks UI debugging

Memory Management

VS Code Memory Crashes: Files >10k lines cause unresponsiveness
Solution Configuration:

{
  "prettier.enableDebugLogs": true,
  "prettier.resolveGlobalModules": false,
  "typescript.preferences.includePackageJsonAutoImports": "off"
}

Large File Handling:

// prettier-ignore-start
const hugeGeneratedObject = {
  // 5000 lines of generated code
};
// prettier-ignore-end

Configuration Hierarchy and Conflicts

Config Loading Order (first found wins)

1. .prettierrc in current directory
2. .prettierrc.js or prettier.config.js
3. package.json "prettier" section
4. Default settings

Debug Config Loading:

npx prettier --find-config-path your-file.js

ESLint-Prettier Conflict Resolution

Required Package: eslint-config-prettier
Configuration:

{
  "extends": ["your-existing-config", "prettier"]
}

Verification: npx eslint-config-prettier src/your-file.js should show no conflicts

Monorepo Configuration Disasters

"Works in Root, Breaks in Packages" Problem

Root Cause: VS Code searches upward, gets confused by multiple package.json files
Solution Pattern:

1. Shared config in monorepo root:

// prettier.config.js (root)
module.exports = {
  printWidth: 120,
  singleQuote: true,
  trailingComma: 'all',
  semi: true
};

2. Link from each package:

// packages/app/prettier.config.js
module.exports = require('../../prettier.config.js');

3. Force local config path:

{
  "prettier.configPath": "./prettier.config.js",
  "prettier.requireConfig": true
}

ESM Import Errors (Prettier 3.0+ Breaking Change)

Error: Cannot use import statement outside a module
Cause: Prettier 3.0+ doesn't support ES6 imports in config by default

Solution Options:

1. Use .mjs extension: prettier.config.mjs
2. Use CommonJS: module.exports = {}
3. Add "type": "module" to package.json

Production Environment Failures

CI/CD Common Failures

Symptom: Works locally, fails in CI
Root Causes (frequency order):

1. Different Prettier versions between developers
2. Platform-specific line ending issues (CRLF vs LF)
3. Node.js version differences
4. Missing .prettierrc in CI environment

Version Lockdown Strategy:

{
  "devDependencies": {
    "prettier": "3.6.0"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

CI Script Pattern:

npm ci --ignore-scripts
npx prettier --check . --ignore-path .gitignore
if [ $? -ne 0 ]; then
  echo "Code not formatted. Run 'npm run format' locally"
  exit 1
fi

Line Ending Hell (Cross-Platform)

Symptoms: Every line shows as modified in Git, different formatting per OS
Permanent Fix Sequence:

1. Git configuration:

git config --global core.autocrlf input   # Mac/Linux
git config --global core.autocrlf true    # Windows

2. .editorconfig:

root = true
[*]
end_of_line = lf

3. Prettier config:

{
  "endOfLine": "lf",
  "insertFinalNewline": true
}

Docker Container Issues

Common Failures:

• Different Node.js versions
• Missing native dependencies (Alpine Linux)
• File permissions preventing writes
• Memory limits too low

Production Dockerfile Pattern:

FROM node:18.17.0-alpine
RUN npm install -g prettier@3.6.0
ENV NODE_OPTIONS="--max-old-space-size=4096"
RUN addgroup -g 1001 -S nodejs && adduser -S nextjs -u 1001
USER nextjs

Error Classification and Time Investment

Error Type	Fix Time	Severity	Frequency
Red button in VS Code	2 minutes	Low	Very High
SyntaxError: Unexpected token	5-15 minutes	Medium	High
Format on save not working	1 minute	Low	High
Configuration not found	3 minutes	Low	Medium
ESLint conflicts	5 minutes	Medium	Medium
Slow performance (2+ min)	10 minutes	High	Medium
Plugin not loading	15-30 minutes	Medium	Low
Monorepo config chaos	20-45 minutes	High	Low
Memory crashes	5 minutes	High	Low
Import errors in config	2 minutes	Low	Medium

Critical Performance Thresholds

Speed Benchmarks

• Baseline (JavaScript parser): 4 minutes 23 seconds for 180k lines
• Rust parser (@prettier/plugin-oxc): 18 seconds for same codebase
• Breaking Point: UI becomes unusable at 1000+ spans for debugging
• Memory Limit: VS Code crashes on files >10k lines without optimization

Resource Requirements

• Memory: 4GB+ Node.js heap for large codebases
• Expertise: 15-30 minutes plugin debugging requires advanced knowledge
• Team Coordination: 20-45 minutes monorepo setup affects entire team

Version Compatibility Matrix

Critical Compatibility Issues

• Prettier 3.0+ Breaking Change: ESM config support removed
• Plugin Compatibility: Many plugins don't support Prettier 3.x
• Node.js Requirements: Prettier 3.6+ requires Node 18+
• VS Code Extension: Version mismatches cause silent failures

Migration Costs

• Small Project (<10k lines): 1-2 hours initial setup
• Large Codebase (50k+ lines): 1-2 days with incremental migration
• Monorepo: 2-3 days including team coordination
• Legacy System: 1 week+ with custom parser requirements

Common Misconceptions and Hidden Costs

False Assumptions

• "Global Prettier works everywhere": Causes version conflicts
• "Default settings are production-ready": Break on large files
• "Config files are optional": Required for team consistency
• "All editors work the same": VS Code needs specific configuration

Hidden Time Costs

• Plugin ecosystem navigation: 2-4 hours researching compatibility
• Team onboarding: 1 hour per developer for consistent setup
• CI/CD debugging: 4-8 hours for cross-platform issues
• Legacy code migration: 40+ hours for large codebases

Decision Criteria for Alternatives

When Prettier Isn't Worth It

• Single developer projects: Setup overhead exceeds benefits
• Legacy codebases: Migration cost >40 hours
• Performance-critical pipelines: 2+ minute formatting unacceptable
• Highly customized styling: Prettier's opinionated nature conflicts

Alternative Tool Comparison

• Biome: 10x faster than Prettier, but less mature ecosystem
• dprint: Rust-based, configuration complexity higher
• Standard: Zero configuration, but less flexible
• ESLint --fix: Limited formatting scope, performance issues at scale

Operational Warnings

Production Killers

• Memory crashes in CI: Node.js heap exhaustion on large files
• Version drift: Team members using different Prettier versions
• Line ending chaos: Windows/Mac teams without proper Git config
• Plugin dependency hell: Conflicting plugin versions break formatting

Early Warning Signs

• Inconsistent formatting: Version or config drift
• Slow CI builds: Memory or performance optimization needed
• Red error icons: Default formatter or extension issues
• Git diff noise: Line ending configuration problems

Recovery Procedures

• Complete VS Code reset: Kill process, reinstall extension
• Config debugging: Use CLI tools to trace config loading
• Performance rescue: Switch to Rust parser, enable caching
• Team synchronization: Lock versions, commit config files