Fix Build Errors

Fix Build Errors

When to Use

• Build or compilation fails after code changes
• CI pipeline reports build failures
• TypeScript, ESLint, or other static analysis errors
• Dependency resolution failures after package updates
• Build works locally but fails in CI (or vice versa)

Prerequisites

• Access to the build command and its output
• The project's build toolchain is installed
• Source control so you can compare against a known-good state

Workflow

1. Capture the Full Error Output

# Run the build and capture output — use task agent to keep context clean
npm run build 2>&1 | Out-String

Or use the task agent for long builds:

task agent_type: "task"
prompt: "Run 'npm run build' and report all errors"

2. Categorize the Errors

Read errors from top to bottom — later errors are often caused by earlier ones.

| Error Type | Example | Typical Fix | |-----------|---------|-------------| | Import/Module | Cannot find module 'x' | Install dependency, fix path | | Type | Type 'string' not assignable to 'number' | Fix type annotation or cast | | Syntax | Unexpected token | Fix syntax error, check for missing brackets | | Lint | no-unused-vars | Remove unused variable or disable rule | | Config | Invalid tsconfig option | Fix config file | | Dependency | Peer dependency not met | Install or update package |

3. Fix the Root Cause (Not Symptoms)

# Find the first error — it's usually the root cause
npm run build 2>&1 | Select-String "error" | Select-Object -First 5

# Navigate to the file and line
# Use view tool to see context around the error

For import errors:

# Check if the module exists
glob pattern="**/*moduleName*"

# Check if it's installed
npm ls module-name 2>&1

For type errors:

# See the full type definition
grep -rn "interface|type" --include="*.ts" -A 5 src/ | Select-String "TypeName"

4. Apply the Fix

Use edit for surgical changes to specific lines:

edit path: "src/broken-file.ts"
old_str: "const x: string = 42;"
new_str: "const x: number = 42;"

5. Verify the Fix

# Rebuild — should succeed now
npm run build 2>&1 | Select-Object -Last 10

# Run tests to ensure the fix didn't break behavior
npm test 2>&1 | Select-Object -Last 10

6. Handle Cascading Errors

If fixing one error reveals more:

1. Rebuild after each fix
2. Address new errors from top to bottom
3. If the error count isn't decreasing, you may be fixing symptoms — step back and find the root cause

Examples

Missing Dependency

# Error: Cannot find module 'lodash'
npm install lodash
npm install --save-dev @types/lodash  # for TypeScript

npm run build

TypeScript Strict Mode Errors After Upgrade

# Find all strictNullChecks errors
npx tsc --noEmit 2>&1 | Select-String "possibly 'null'" | Measure-Object -Line

# Fix them one file at a time, starting with leaf modules (no imports from your code)
npx tsc --noEmit 2>&1 | Select-String "possibly 'null'" | Select-Object -First 3

CI vs Local Mismatch

# Check Node/npm version differences
node --version
npm --version

# Check for OS-specific path issues
grep -rn "\\\\" src/ --include="*.ts"  # Windows backslashes in code

# Check for missing environment variables
grep -rn "process.env" src/ --include="*.ts" | Select-String -NotMatch "NODE_ENV"

Tips

• Fix the first error first — many later errors are caused by earlier ones
• Use task agent to run builds — it returns brief output on success, full output on failure
• After fixing, always run the full test suite, not just the build
• If a dependency update caused the break, check its changelog for breaking changes
• For persistent issues, compare against the last known-good commit:

``powershell git --no-pager log --oneline -10 git --no-pager diff -- src/ ``

• Keep tsconfig.json / build configs in source control so you can diff changes

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: drvoss
• Source: drvoss/everything-copilot-cli
• License: MIT

Install and usage instructions live in the source repository linked above.