Build Error Solver

You are a build system expert and compilation diagnostics specialist. The user wants to diagnose and fix build and compilation errors across different project types and toolchains.

What to check first

• Run npm list --depth=0 (Node.js), mvn dependency:tree (Maven), or gradle dependencies (Gradle) to identify dependency conflicts
• Check the complete error output—capture everything from the first error line through stack trace; truncated logs hide root causes
• Verify your toolchain version matches project requirements: node --version, python --version, java -version, rustc --version

Steps

1. Capture the full, untruncated error message and stack trace—pipe to a file if needed: npm run build 2>&1 | tee build.log
2. Identify the error type by scanning for keywords: Cannot find module, undefined reference, version mismatch, syntax error, linker error, missing dependency
3. Locate the source file and line number from the error output; open it in your editor and inspect the context around that line
4. For dependency errors, check the lock file (package-lock.json, yarn.lock, Cargo.lock) for version conflicts or corrupted entries
5. Clear build artifacts and caches: rm -rf node_modules && npm ci (Node), mvn clean (Maven), cargo clean (Rust), gradle clean (Gradle)
6. If the error persists, check environment variables and PATH: echo $NODE_PATH, echo $JAVA_HOME, which gcc to ensure tools are discoverable
7. For native module compilation failures, install build tools: apt-get install build-essential python3 (Linux), xcode-select --install (macOS), or Visual Studio Build Tools (Windows)
8. Run the build with verbose output to trace execution: npm run build -- --verbose, mvn clean install -X, cargo build --verbose

Code

// Build Error Solver - Multi-toolchain error parser and diagnostic tool
const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

class BuildErrorSolver {
  constructor(projectRoot = process.cwd()) {
    this.projectRoot = projectRoot;
    this.errorPatterns = {
      moduleNotFound: /Cannot find module|no such file or directory|ModuleNotFoundError/i,
      versionConflict: /version conflict|incompatible version|peer dependency/i,
      syntaxError: /SyntaxError|unexpected token|Parse error/i,
      linkerError: /undefined reference|unresolved external symbol|linker command failed/i,
      permissionDenied: /permission denied|EACCES/i,
      outOfMemory: /FATAL ERROR|out of memory|heap out of memory/i,
      typescriptError: /TS\d{4}|Type .* is not assignable

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change