Env Troubleshooting

Environment Troubleshooting Skill

This skill provides systematic solutions for resolving common development environment startup failures, focusing on Go and Node.js/NPM ecosystems.

1. Go Version Mismatch

Symptoms:

• Error: compile: version "go1.X" does not match go tool version "go1.Y"
• Error: go: cannot run *go1.X* (installed in ...) please ensure that go1.X is in your PATH

Diagnosis: The version specified in go.mod differs from the local go toolchain, or the toolchain auto-download mechanism is failing. Often caused by GOROOT environment variable pointing to an older system installation while go binary is newer.

Solutions:

1. Force Local Toolchain (Recommended for dev): Tell Go to use the locally installed version regardless of go.mod.

   go env -w GOTOOLCHAIN=local
   go clean -cache
   

2. Fix GOROOT Mismatch (Critical if Solution 1 fails): If go version shows X but go env GOROOT shows Y, explicit export is needed.

   # Check current GOROOT
   go env GOROOT
   # Find correct toolchain path (example for Mac)
   ls -d ~/go/pkg/mod/golang.org/toolchain@*
   # Set GOROOT (replace path with actual one found above)
   export GOROOT=/Users/<user>/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.25.6.darwin-amd64
   export PATH=$GOROOT/bin:$PATH
   

3. Match go.mod: Update go.mod to match your local version (if permissible).

   go mod edit -go=1.25.6  # Replace with your `go version`
   go mod tidy
   

2. NPM Dependency Conflicts

Symptoms:

• Error: ERESOLVE unable to resolve dependency tree
• Error: Conflicting peer dependency: ...

Diagnosis: Strict peer dependency checks in npm v7+ are failing because libraries require different versions of the same package (e.g., React or Ant Design).

Solutions:

1. Legacy Peer Deps (Quick Fix): Bypass strict peer dependency checks. Safe for dev, but check for runtime errors.

   npm install --legacy-peer-deps
   

2. Force Install (Aggressive):

   npm install --force
   

3. Resolution Override (Best Practice): Add a overrides (npm) or resolutions (yarn) section to package.json to force a specific version.

   "overrides": {
     "antd": "^5.0.0"
   }
   

3. Port Conflicts

Symptoms:

• Error: listen tcp :8090: bind: address already in use

Solutions:

1. Find and Kill:

   lsof -i :8090
   kill -9 <PID>
   

2. Change Port: Update config.yaml or .env to use a free port.

Workflow

1. Analyze Error Log: Identify keywords (compile version, ERESOLVE, bind).
2. Apply Fix: Use the corresponding solution above.
3. Clean & Rebuild: Always run go clean -cache or rm -rf node_modules after major env changes.
4. Verify: Start the service and check health endpoints.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.