Silent Failure When .env Contains Invalid Variable Names

[jongio]

Summary

azd app run silently fails to load all environment variables when the .azure/[env]/.env file contains an environment variable name with hyphens (e.g., MY-INVALID-VAR). The entire .env file fails to parse and no environment variables are loaded at all.

Expected Behavior

azd should either:

1. Display a clear error message indicating which line/variable name is invalid, OR
2. Skip the invalid variable and load the remaining valid variables, OR
3. Provide validation feedback before attempting to run services

Actual Behavior

• azd app run starts all services successfully but with zero environment variables loaded
• Prerun hooks and services show all variables as "NOT SET"
• Services fail at runtime due to missing configuration
• The only error appears when running azd env get-values:

  ERROR: ensuring environment exists: loading .env: unexpected character "-" in variable name near "MY-INVALID-VAR=..."
  

• This error is not shown during azd app run, making it difficult to diagnose

Steps to Reproduce

1. Create .azure/dev1/.env with a variable name containing hyphens:

   VALID_VAR="value1"
   MY-INVALID-VAR="value2"
   ANOTHER_VALID_VAR="value3"
   AZURE_ENV_NAME="dev1"

2. Run azd app run

3. Observe that services start but NO environment variables are loaded (not even VALID_VAR or AZURE_ENV_NAME)

4. Run azd env get-values to see the parsing error (this is the only place the error surfaces)

Environment

• azd version: [run azd version]
• OS: Windows
• Shell: PowerShell

Impact

This is a critical usability issue because:

• The failure is silent during azd app run - services start successfully despite missing all configuration
• Developers waste time debugging their application code instead of the .env syntax
• The error only surfaces when manually running azd env get-values
• All environment variables fail to load (not just the invalid one), causing cascading failures

Example Symptoms

When a prerun hook checks environment variables:

========================================
Environment Variables Check
========================================

❌ VITE_CLIENT_ID = NOT SET
❌ VITE_TENANT_NAME = NOT SET
❌ VITE_AUTH_DOMAIN = NOT SET
❌ AZURE_ENV_NAME = NOT SET

Summary: 0/8 variables set
========================================

Yet the services start successfully, leading developers to believe the issue is with their application rather than the environment configuration.

Suggested Fix

• Validate .env file syntax before starting services
• Display clear error messages with line numbers and invalid variable names
• Consider failing fast with a descriptive error rather than proceeding with empty environment
• Add validation to azd env set or azd env refresh commands to catch issues earlier

Workaround

Ensure all environment variable names use only:

• Uppercase letters (A-Z)
• Numbers (0-9)
• Underscores (_)

Do not use hyphens/dashes (-) in variable names.

Valid: E2E_ADMIN_PASSWORD, MY_VAR_NAME_123
Invalid: E2E-ADMIN-PASSWORD, MY-VAR-NAME

Related

This follows POSIX shell variable naming conventions, which azd appears to enforce but does not validate or communicate clearly to users.