Environment Variable Validator

Understanding .env Files

Environment variables are a fundamental mechanism for configuring applications without hardcoding values in source code. The .env file convention, popularized by the twelve-factor app methodology, stores these variables as simple key-value pairs in a file at the project root. Libraries like dotenv (available for Ruby, Python, Node.js, PHP, and most other languages) load the file at application startup and inject the variables into the process environment where they can be read with ENV["KEY"], os.environ["KEY"], or process.env.KEY depending on the language.

A well-structured .env file separates configuration from code, making it easy to change settings between development, staging, and production without modifying any source files. Database connection strings, API endpoint URLs, feature flags, third-party service credentials, and application-specific settings all belong in environment variables. The .env file provides a convenient way to manage these variables locally while production deployments use environment variables set by the hosting platform, container orchestrator, or secrets manager.

Common .env File Errors

The most frequent error in .env files is empty values. A line like DATABASE_URL= with no value after the equals sign sets the variable to an empty string, which typically causes a connection failure or configuration error at runtime. This often happens when a developer copies .env.example and forgets to fill in a value, or when a value is accidentally deleted during editing. This validator flags every key with an empty value so you can catch these issues before starting your application.

Duplicate Keys

When the same key appears multiple times in a .env file, the behavior depends on the loader. Ruby's dotenv gem uses the first occurrence by default, Node.js dotenv also uses the first, but shell sourcing with source .env uses the last occurrence. This inconsistency means duplicate keys can cause different behavior in different environments. The solution is to ensure each key appears exactly once. If you need environment-specific overrides, use separate files like .env.development and .env.test that your loader merges in the correct priority order.

Unquoted Values with Spaces

A value like APP_NAME=My Application works correctly with most modern dotenv libraries, but some older parsers and shell-based loaders truncate the value at the first space, reading only My. Wrapping the value in double quotes (APP_NAME="My Application") ensures the full string is preserved across all parsers. Single quotes also work but prevent variable interpolation in loaders that support it. The validator flags unquoted values containing spaces as a warning since they may work in your specific setup but could break if you switch loaders or deploy to a different platform.

Sensitive Data Exposure

Keys containing words like PASSWORD, SECRET, KEY, TOKEN, API_KEY, PRIVATE, or CREDENTIAL almost certainly hold sensitive values. The validator flags these keys as a reminder that their values require special handling. Sensitive variables should never be committed to version control, logged in plaintext, or exposed in error messages. In production, use a secrets manager like AWS Secrets Manager, HashiCorp Vault, or your platform's built-in secrets feature rather than a .env file. If a sensitive value is accidentally committed, consider it compromised and rotate it immediately.

Syntax Validation

Lines that do not contain an equals sign and are not comments (starting with #) are invalid in a .env file. The validator detects these malformed lines and reports them with their line numbers so you can quickly fix typos like missing equals signs or accidentally concatenated lines. Comments are supported with a leading # character, and the validator also detects commented-out variables as a convenience so you can review whether they should be re-enabled or removed.

Frequently Asked Questions

What is a .env file?

A file storing environment variables as KEY=VALUE pairs, one per line. Applications load it at startup to configure database connections, API keys, and settings without hardcoding values in source code.

What errors does this tool check?

Empty values, missing equals signs, duplicate keys, unquoted spaces in values, and sensitive keys containing PASSWORD, SECRET, KEY, TOKEN, or similar patterns.

Why should values with spaces be quoted?

Some parsers split on whitespace. Quoting ensures the full value is preserved. Use double quotes for compatibility across all dotenv libraries and shell environments.

What do I do about duplicate keys?

Remove duplicates so each key appears once. Different loaders handle duplicates differently, creating inconsistent behavior between environments.

Why are sensitive keys flagged?

Keys with PASSWORD, SECRET, KEY, or TOKEN likely hold credentials that should never be committed to Git. The flag reminds you to protect these values and rotate them if exposed.