Troubleshooting

Common issues and solutions when using envcheck

Common Issues

Config File Not Found

Error Message:

Error: Config file not found

Cause: envcheck looks for .envcheck.yaml in the current directory by default.

Solutions:

Create a config file

Initialize a new config file in your project root:

envcheck init

This creates a .envcheck.yaml file with example configuration.

Specify config path

Use the --config flag to point to your config file:

envcheck --config /path/to/.envcheck.yaml

Or use a relative path:

envcheck --config ./config/.envcheck.yaml

Check current directory

Make sure you’re running envcheck from the correct directory:

ls -la .envcheck.yaml  # Verify file exists
pwd                     # Check current directory

Invalid YAML Syntax

Error Message:

Error: Failed to parse config: invalid yaml syntax

Cause: Your .envcheck.yaml file has syntax errors.

Solutions:

1. Check indentation

   YAML is whitespace-sensitive. Use 2 spaces for indentation (not tabs):

   version: "1"
   tools:  # Correct: 2 spaces
     - name: node
       version: ">=18.0.0"  # Correct: 4 spaces (2 levels)
   
2. Validate quotes

   Version strings must be quoted:

   # ❌ Incorrect
   version: 1
   
   # ✅ Correct
   version: "1"
   
3. Use a YAML validator

   Validate your YAML syntax online or with a tool:

   # Using yamllint
   yamllint .envcheck.yaml
   
   # Using Python
   python -c "import yaml; yaml.safe_load(open('.envcheck.yaml'))"
   

Tool Not Found

Error Message:

✗ node not found

Cause: The required tool is not installed or not in your PATH.

Solutions:

Install the tool

Install the missing tool:

# Node.js
# Visit https://nodejs.org or use a version manager:
nvm install 18

# Docker
# Visit https://docs.docker.com/get-docker/

# Git
sudo apt-get install git  # Ubuntu/Debian
brew install git          # macOS

Check PATH

Verify the tool is in your PATH:

which node    # Should show path to node binary
echo $PATH    # View all directories in PATH

If not in PATH, add it to your shell profile:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Use verbose mode

Run with --verbose to see more details:

envcheck --verbose

Version Mismatch

Error Message:

✗ node version 16.20.0 does not satisfy requirement >=18.0.0

Cause: The installed version doesn’t meet the requirements specified in your config.

Solutions:

Upgrade the tool

Upgrade to a compatible version:

# Using nvm for Node.js
nvm install 18
nvm use 18

# Update default version
nvm alias default 18

Update config requirement

If the installed version is acceptable, update .envcheck.yaml:

tools:
  # Change requirement to match installed version
  - name: node
    version: ">=16.0.0"  # Was ">=18.0.0"

Use version managers

Use version managers to switch between versions:

# Node Version Manager (nvm)
nvm use 18

# rbenv for Ruby
rbenv local 3.2.0

# pyenv for Python
pyenv local 3.11.0

Environment Variable Not Set

Error Message:

✗ DATABASE_URL is not set

Cause: A required environment variable is missing.

Solutions:

Set the environment variable

Set the variable in your shell:

export DATABASE_URL="postgresql://localhost/mydb"

Or add to your shell profile for persistence:

# Add to ~/.bashrc or ~/.zshrc
echo 'export DATABASE_URL="postgresql://localhost/mydb"' >> ~/.bashrc
source ~/.bashrc

Use a .env file

Create a .env file and load it before running envcheck:

.env

DATABASE_URL=postgresql://localhost/mydb
API_KEY=your-api-key

Load it using source or export:

# Using export
export $(cat .env | xargs)
envcheck

# Or run in same command
export $(cat .env | xargs) && envcheck

Mark as optional

If the variable is not critical, mark it as optional:

env_vars:
  - name: DATABASE_URL
    required: false  # Won't fail if missing

Port Already in Use

Error Message:

⚠ Port 3000 is in use

Cause: Another process is already using the required port.

Solutions:

Find the process using the port

Identify what’s using the port:

# Linux/macOS
lsof -i :3000

# Alternative using netstat
netstat -tuln | grep 3000

# Windows
netstat -ano | findstr :3000

Stop the conflicting process

Kill the process using the port:

# Find PID from lsof output, then:
kill -9 <PID>

# Or if it's a known service:
sudo systemctl stop myservice

Use a different port

Configure your application to use a different port:

.envcheck.yaml

ports:
  - 3001  # Changed from 3000

File Not Found

Error Message:

✗ .env does not exist

Cause: A required file is missing.

Solutions:

Create the file

Create the missing file:

touch .env

# Or copy from example:
cp .env.example .env

Check file path

Verify the path in your config is correct:

files:
  - path: .env          # Correct: relative to project root
  - path: config/.env   # Check subdirectory

Mark as optional

If the file is not critical:

files:
  - path: .env
    required: false  # Won't fail if missing

Network Check Failing

Error Message:

✗ Failed to connect to https://api.example.com

Cause: Network connectivity issues or the service is down.

Solutions:

Check internet connection

Verify you have internet access:

ping google.com
curl -I https://api.example.com

Check firewall/proxy

Corporate firewalls may block requests. Try:

# Set proxy if needed
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

envcheck

Verify the URL

Make sure the URL is correct and accessible:

network:
  - url: https://api.example.com  # Check this is correct
    status_code: 200

Remove network check for offline development

If working offline, comment out network checks:

# network:
#   - url: https://api.example.com

Debugging Tips

Use Verbose Mode

Enable verbose output to see detailed information:

envcheck --verbose

This shows:

• Config file loading details
• Exact version numbers detected
• Full error messages
• Debug information

Use JSON Output

Get structured output for easier debugging:

envcheck --json | jq .

Filter for specific issues:

# Show only errors
envcheck --json | jq -r '.results[] | select(.status == "error")'

# Show errors with suggestions
envcheck --json | jq -r '.results[] | select(.status == "error") | "\(.message)\n  → \(.suggestion)"'

Check Config Location

envcheck searches for config in this order:

1. Path specified with --config flag
2. .envcheck.yaml in current directory
3. .envcheck.yaml in parent directories (up to git root)

Verify which config is being used:

envcheck --verbose 2>&1 | grep "Loaded config"

Validate Semver Requirements

Test your version requirements:

# Check what version is detected
node --version

# Verify it matches your requirement
# Requirement: ">=18.0.0"
# Installed: "v18.17.0" → ✅ Valid
# Installed: "v16.20.0" → ❌ Invalid

Common semver patterns:

• ">=18.0.0" - At least 18.0.0
• "^18.0.0" - Compatible with 18.x.x (18.0.0 to 18.99.99)
• "~18.0.0" - Approximately 18.0.x (18.0.0 to 18.0.99)
• "*" - Any version

Getting Help

GitHub Issues

Report bugs or request features

Configuration Reference

Review all configuration options

CLI Commands

See all available commands and flags

Examples

Check out working examples

If you encounter an issue not listed here, please open an issue on GitHub with:

• Output from envcheck --verbose
• Your .envcheck.yaml config (remove any secrets)
• Your environment (OS, shell, tool versions)