AWS Lambda Error: Environment variable ‘XYZ’ is undefined

#aws#lambda#devops#cloud

Undefined environment variables happen when Lambda’s deployed configuration does not match what your code expects

Problem

Your Lambda executes but immediately fails when accessing an environment variable. CloudWatch shows errors such as:

KeyError: 'DB_HOST'

or

Error: process.env.API_KEY is undefined

Lambda itself is running — but the environment variable your code expects is not present.

• Environment variable never defined in the Lambda configuration
• Wrong casing or misspelled variable names
• CDK/SAM/Terraform variables not deployed or assigned to the intended stage

---

Clarifying the Issue

Environment variables in Lambda are injected at deployment time. If a variable is missing, empty, spelled incorrectly, or tied to the wrong stage/alias, the runtime cannot access it. Lambda will not warn you during deployment — it simply runs without the variable.

• Environment variables do not propagate across versions or aliases
• Deployment tools can skip unchanged configuration blocks
• Changing code or roles does not update environment variables
• Empty-string values behave differently per runtime, but KeyError/undefined specifically indicates the variable was never injected

---

Why It Matters

Missing environment variables cause immediate execution failures. Configuration values like credentials, URLs, and API keys often live here, so any mismatch breaks your request flow.

• API Gateway endpoints fail instantly
• Event-driven Lambdas retry endlessly
• Stage-to-stage drift creates unpredictable system behavior

---

Key Terms

• Environment variable – A key/value pair injected into Lambda at runtime
• Configuration drift – When deployed settings differ from expected definitions
• Deployment provider – CDK, SAM, Terraform, or console-based Lambda config

---

Steps at a Glance

1. Confirm the runtime error in CloudWatch logs
2. Check the environment variable configuration for the Lambda
3. Verify spelling, casing, and naming
4. Compare deployed variables against CDK/SAM/Terraform
5. Confirm stage, alias, and version alignment
6. Re-deploy environment configuration
7. Test with a manual invocation
8. Validate SSM/Secrets Manager parameter references

---

Detailed Steps

Step 1: Confirm the runtime error in CloudWatch logs.

Check recent invocation logs:

aws logs tail /aws/lambda/my-function --since 5m

Common errors include:

KeyError: 'DB_PASSWORD'

or

TypeError: Cannot read property 'API_KEY' of undefined

This confirms the variable is missing. Now inspect the deployed configuration.

---

Step 2: Check the environment variable configuration for the Lambda.

Get the environment block:

aws lambda get-function-configuration \
  --function-name my-function \
  --query 'Environment.Variables'

If your variable does not appear here, Lambda never received it.

---

Step 3: Verify spelling, casing, and naming.

Environment variables are case-sensitive.

Examples:

API_KEY   ≠   Api_Key
DB_HOST   ≠   db_host
PAYMENT_URL   ≠   PAYMENTS_URL

Confirm your code and configuration match character-for-character.

---

Step 4: Compare deployed variables against CDK/SAM/Terraform definitions.

CDK:

environment: {
  DB_HOST: "db.example.com"
}

SAM:

Environment:
  Variables:
    DB_HOST: db.example.com

Terraform:

environment {
  variables = {
    DB_HOST = "db.example.com"
  }
}

If the infrastructure config is correct but missing in Lambda, you have drift.

---

Step 5: Confirm stage, alias, and version alignment.

Aliases point to specific published versions, each with their own environment variables.

aws lambda get-alias \
  --function-name my-function \
  --name prod

If you're invoking an older version, your updated environment variables are not applied.

---

Step 6: Re-deploy environment configuration.

Apply updated environment settings directly:

aws lambda update-function-configuration \
  --function-name my-function \
  --environment "Variables={DB_HOST=db.example.com}"

With SAM/CDK/Terraform, run a full deploy, not partial updates.

---

Step 7: Test with a manual invocation.

aws lambda invoke \
  --function-name my-function \
  --payload '{}' \
  out.json

Check CloudWatch again for undefined variable errors.

---

Step 8: Validate SSM Parameter Store or Secrets Manager references.

If you use parameters:

aws ssm get-parameter --name "/myapp/dev/db_password"

Secrets:

aws secretsmanager get-secret-value \
  --secret-id my-db-secret

If the Lambda execution role lacks ssm:GetParameter or secretsmanager:GetSecretValue, the value cannot be retrieved and the variable will not be injected.

---

Pro Tips

• Remember resolution time: env vars and SSM/Secrets (via substitution syntax) are injected at deploy time, not runtime
• Retrieve secrets dynamically in code when values change frequently
• Use alias-specific variables for dev/stage/prod separation

---

Conclusion

Undefined environment variables happen when Lambda’s deployed configuration does not match what your code expects. By checking logs, validating the environment block, confirming alias alignment, and redeploying configuration, you can eliminate these failures and stabilize your workloads.

---

Aaron Rose is a software engineer and technology writer at tech-reader.blog and the author of Think Like a Genius.