infrastructure-debugging

majiayu000's avatarfrom majiayu000

Troubleshooting dependencies, installations, environment issues, and platform-specific problems. Use when facing npm/pip/package errors, installation failures, environment setup issues, or platform compatibility problems.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026
[Debugging]

When & Why to Use This Skill

The Infrastructure Debugging skill is a specialized diagnostic tool designed to resolve complex software environment issues, dependency conflicts, and platform-specific installation failures. It provides expert guidance on troubleshooting package managers like npm and pip, managing cross-platform compatibility (Windows, macOS, Linux), and optimizing system-level configurations to ensure a stable and reproducible development environment.

Use Cases

  • Case 1: Resolving package manager conflicts such as npm ERESOLVE errors, peer dependency mismatches, or pip version inconsistencies within virtual environments.
  • Case 2: Fixing environment-specific installation failures, including native module compilation issues on macOS (M1/M2) or Windows-specific path length and permission constraints.
  • Case 3: Recovering corrupted development environments by identifying root causes in system dependencies, cache corruption, or incorrect PATH configurations.
  • Case 4: Standardizing cross-platform setup by providing checklists for runtime versions, build tools (Xcode/Visual Studio), and shell-specific environment variables.
nameinfrastructure-debugging
descriptionTroubleshooting dependencies, installations, environment issues, and platform-specific problems. Use when facing npm/pip/package errors, installation failures, environment setup issues, or platform compatibility problems.

Infrastructure Debugging

Dependency Resolution Strategy

When Facing Package Errors

  1. Read the full error: Scroll up to find the root cause, not just the final message
  2. Check version compatibility: Many issues stem from version mismatches
  3. Clear caches first: npm cache clean --force or pip cache purge
  4. Try fresh install: Delete lock files and node_modules/venv, reinstall
  5. Check peer dependencies: Especially for React, TypeScript, and build tools

Common Package Manager Issues

npm/yarn/pnpm:

  • ERESOLVE errors: Try --legacy-peer-deps or update conflicting packages
  • EACCES permission errors: Don't use sudo, fix npm permissions instead
  • Phantom dependencies: Use pnpm for stricter resolution

pip/poetry/uv:

  • Version conflicts: Use virtual environments, always
  • Build failures: Check for missing system dependencies (gcc, python-dev)
  • Wheel issues: Try --no-binary :all: or update pip

Environment Setup

Best Practices

  1. Isolate environments: Use venv, nvm, containers
  2. Document versions: Pin exact versions for reproducibility
  3. Check PATH: Many issues come from wrong binary being used
  4. Verify installation: Test imports/commands after installing

Platform-Specific Issues

Windows:

  • Path length limits (260 chars): Enable long paths or use shorter paths
  • Line endings: Configure git to handle CRLF/LF properly
  • Native modules: May need Visual Studio Build Tools
  • WSL vs native: Know which environment you're targeting

macOS:

  • Xcode Command Line Tools required for many packages
  • Homebrew vs system Python: Be explicit about which
  • M1/M2 ARM: Some packages need Rosetta or ARM builds

Linux:

  • Missing system dependencies: Check package manager (apt, yum, etc.)
  • Permission issues: Avoid sudo for user packages
  • Library paths: Check LD_LIBRARY_PATH if linking fails

Troubleshooting Checklist

  1. What exact error message?
  2. What OS and version?
  3. What package manager and version?
  4. What Node/Python/runtime version?
  5. Is this a fresh install or upgrade?
  6. What changed recently?

Accumulated Learnings

See learnings.md for session-learned insights about infrastructure issues.