Troubleshooting Guide

This guide helps you diagnose and solve common issues that may arise when using EnvWizard.

Installation Issues

Command Not Found

Problem:

command not found: env-mage

Solutions:

Check global installation:
```
npm list -g env-mage
```

Reinstall globally:

npm uninstall -g env-mage
npm install -g env-mage

Use via npx if locally installed:
```
npx env-mage <command>
```
Check your PATH environment variable:
- Ensure npm's global bin directory is in your PATH
- For npm: npm config get prefix + '/bin' should be in PATH
- For yarn: yarn global bin should be in PATH

Permission Errors

Problem:

EACCES: permission denied

Solutions:

Use sudo (not recommended):
```
sudo npm install -g env-mage
```

Fix npm permissions:

# Change ownership of npm directories
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

Use nvm (Node Version Manager) to install Node.js:
- This avoids permission issues by installing in your user directory

Dependency Conflicts

Problem:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

Solutions:

Force install:
```
npm install --force env-mage
```
Clear npm cache:
```
npm cache clean --force
```
Update npm:
```
npm install -g npm@latest
```

Command Execution Issues

`.env` File Not Found

Problem:

Error: Could not find .env file at /path/to/project/.env

Solutions:

Create the file:
```
touch .env
```

Specify a different path:

env-mage <command> --env /path/to/your/.env

Check file permissions:

ls -la .env
chmod 600 .env  # Set proper permissions

Validation Failures

Problem:

Error: Validation failed: Missing required variables: DATABASE_URL, API_KEY

Solutions:

Add the missing variables:
- Add the variables to your .env file
Use a less strict mode for validation:
```
env-mage validate --no-strict
```
Specify required variables:
```
env-mage validate --required VAR1 VAR2
```

Typegen Issues

Problem:

Error: Failed to generate TypeScript types

Solutions:

Check file permissions in the output directory:
```
chmod 755 ./
```

Specify a different output path:

env-mage typegen --output ./src/types/env.types.ts

Check TypeScript installation:

npm install --save-dev typescript @types/node

Scan Command Finds No Variables

Problem:

No environment variables found in the codebase.

Solutions:

Check the file pattern:

env-mage scan --pattern "src/**/*.{js,ts,jsx,tsx}"

Check for different access patterns:

env-mage scan --access-patterns "process.env" "import.meta.env"

Increase verbosity:
```
env-mage scan --verbose
```

CI/CD Integration Issues

GitHub Actions Failures

Problem: EnvWizard commands fail in GitHub Actions

Solutions:

Ensure EnvWizard is installed:

- name: Install EnvWizard
  run: npm install -g env-mage

Create a CI-specific env file:

- name: Setup environment
  run: |
    cp .env.example .env.ci
    echo "DATABASE_URL=${{ secrets.DATABASE_URL }}" >> .env.ci

Run EnvWizard with the CI env file:

- name: Validate environment
  run: env-mage validate --env .env.ci

Docker Build Failures

Problem: EnvWizard commands fail during Docker build

Solutions:

Install EnvWizard in the build stage:

FROM node:16-alpine AS builder
# ...
RUN npm install -g env-mage

Copy example file and create a Docker-specific env file:

COPY .env.example .env.docker
RUN echo "NODE_ENV=production" >> .env.docker

Run with the Docker env file:
```
RUN env-mage validate --env .env.docker
```

Common Error Messages

"Cannot read properties of undefined"

Problem:

TypeError: Cannot read properties of undefined (reading 'VARIABLE_NAME')

Solutions:

Check that the variable exists:

env-mage validate --required VARIABLE_NAME

Add a default value in your code:

const variableName = process.env.VARIABLE_NAME || "default";

"Invalid or incomplete .env file"

Problem:

Error: Invalid or incomplete .env file

Solutions:

Check file format:
```
env-mage lint --fix
```
Validate the file:
```
env-mage validate
```
Check for common syntax issues:
- No spaces around the equals sign: VAR=value (not VAR = value)
- Quotes around values with special characters: VAR="value with spaces"
- No trailing/leading whitespace

"Cannot find module 'env-mage'"

Problem:

Error: Cannot find module 'env-mage'

Solutions:

Install EnvWizard properly:

npm install -g env-mage
# Or locally
npm install --save-dev env-mage

Verify installation:

which env-mage
# Or
npm list -g | grep env-mage

Advanced Troubleshooting

Debugging EnvWizard Commands

Problem: Need more information about what's happening

Solutions:

Enable debug mode:
```
DEBUG=env-mage* env-mage <command>
```
Use verbose flag:
```
env-mage <command> --verbose
```
Use strict mode with detailed output:
```
env-mage <command> --strict --verbose
```

Performance Issues

Problem: EnvWizard commands running slowly

Solutions:

Optimize scanning patterns:

env-mage scan --pattern "src/**/*.{js,ts}" --exclude "node_modules,dist,build"

Reduce the file search scope:
```
env-mage scan --max-files 500
```
Disable verbose logging:
```
env-mage <command> --no-verbose
```

Incompatibility with Other Tools

Problem: Conflicts with other environment management tools

Solutions:

Isolate EnvWizard usage in dedicated scripts:

// package.json
"scripts": {
  "env:check": "env-mage validate",
  "env:setup": "env-mage init && env-mage typegen"
}

Specify explicit file paths to avoid conflicts:
```
env-mage <command> --env ./.env.project
```

Check for tool-specific env variable loading patterns:

env-mage scan --access-patterns "process.env" "config.env" "app.env"

Getting Additional Help

If your issue isn't resolved by this troubleshooting guide:

Check the GitHub repository:
- Look for similar issues or file a new one

Check detailed logs:

DEBUG=* env-mage <command> 2> env-mage-debug.log

Contact the community:
- Discord: EnvWizard Community
- GitHub Discussions: EnvWizard Discussions

Report a bug:

# Capture environment information
node -v > node-version.txt
npm -v >> node-version.txt
env-mage --version >> node-version.txt

# Then attach this file with your bug report

Troubleshooting

On this page