SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsenv-troubleshoot

env-troubleshoot

Deployment & operations

View repository

Updated 10-15 11:00

About this skill

Environment Troubleshooting (Env Troubleshoot)

Characteristics of environment issues: what everyone encounters is different, but the troubleshooting approach is the same. Core method: read the error message → identify the problem category → address it accordingly.

Troubleshooting process

环境报错
  │
  ├─ 1. 读错误信息（完整读，不跳过）
  ├─ 2. 分类问题
  ├─ 3. 按类别排查
  ├─ 4. 修复并验证
  └─ 5. 记录（如果是常见问题，建议加到项目 docs/guides/）

Problem classification and troubleshooting

Category 1: Dependency installation failure

Common errors：

Error characteristics Possible causes Troubleshooting steps
ERESOLVE unable to resolve npm dependency version conflict 1. Read conflict details 2. npm ls <冲突包> 3. Determine which dependency requires an incompatible version
node-gyp rebuild FAILED Native module compilation failure 1. Check node version 2. Check Python/build-tools 3. xcode-select --install(macOS)
EACCES permission denied Insufficient permissions 1. Don't use sudo to install npm 2. Check npm global directory permissions 3. Use nvm to manage node
network timeout Network issues 1. Check proxy settings 2. Switch mirror source npm config set registry
ModuleNotFoundError (Python) Package not installed or virtual environment not activated 1. which python Confirm interpreter 2. Check whether venv is activated 3. pip install -r requirements.txt

Category 2: Service startup failure

Error characteristics Possible causes Troubleshooting steps
EADDRINUSE :::3000 Port occupied lsof -i :3000 Find the occupying process, kill it or switch ports
Error: Cannot find module Missing module 1. rm -rf node_modules && npm install 2. Check path spelling
ECONNREFUSED 127.0.0.1:5432 Dependent service not started Check whether DB/Redis/etc. dependent services are running
Environment variable related errors .env missing or variables missing 1. cp .env.example .env 2. Check required variables against it
SyntaxError: Unexpected token Node/TS version mismatch Check node -v and engines fields, check tsconfig

Category 3: Docker issues

Error characteristics Possible causes Troubleshooting steps
Cannot connect to Docker daemon Docker not started Start Docker Desktop or systemctl start docker
no space left on device Insufficient disk/Docker space docker system prune Clean up unused images and containers
COPY failed: file not found Dockerfile path error Check COPY source path relative to build context
Build stuck at a certain layer Network issues or slow dependency download Check Docker image source configuration
Container exits immediately after startup Startup command error docker logs <container> Check logs

Category 4: Version conflicts

Scenario Troubleshooting steps
Wrong Node.js version 1. node -v 2. Check .nvmrc or engines 3. nvm use switch
Wrong Python version 1. python --version 2. Check pyproject.toml 3. Use pyenv to switch
TypeScript compilation error 1. Check tsconfig.json target 2. npx tsc --version
Global tool version conflict which <tool> Confirm which one is being used; if necessary, use npx to run the project's local version.

Category 5: Permission issues

Scenario Troubleshooting steps
macOS file permissions ls -la Check permissions,chmod fix
Git hook does not have execute permission chmod +x .git/hooks/* or chmod +x .husky/*
SSH key permissions chmod 600 ~/.ssh/id_*，chmod 700 ~/.ssh

Troubleshooting principles

  • Read the error message first: For 80% of environment issues, the error message itself contains the answer. Do not skip the error message and guess directly.
  • Start with the simplest possibility: First check whether the service is started, whether the port is correct, and whether the environment variables are configured, then dig deeper.
  • Reproduction first: If the error described by the user is incomplete, reproduce the problem first before troubleshooting.
  • Do not blindly clean up：rm -rf node_modules is a last resort, not the first step. First understand why the error occurred.
  • Record the solution: If it is a project-specific environment issue, suggest that the user add it to docs/guides/ or the README

General troubleshooting commands quick reference

# Node.js 环境
node -v && npm -v              # 版本检查
npm ls --depth=0               # 已安装依赖
npm cache clean --force        # 清理缓存
npx envinfo                    # 环境信息汇总

# Python 环境
python --version && pip --version
which python                   # 确认解释器路径
pip list                       # 已安装包
python -m venv .venv && source .venv/bin/activate  # 创建虚拟环境

# 端口/进程
lsof -i :3000                  # 查端口占用
kill -9 <PID>                  # 杀进程

# Docker
docker ps -a                   # 所有容器
docker logs <container>        # 容器日志
docker system df               # 磁盘占用
docker system prune            # 清理

# 通用
echo $PATH                     # PATH 检查
env | grep -i proxy            # 代理设置