infrastructure-debugging

name	infrastructure-debugging
description	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.

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.