Summary
envalid is designed specifically for environment-variable validation. In many deployment environments (Docker, Kubernetes, CI systems, .env files), an empty string is often effectively equivalent to “not provided”. For required configuration values such as API keys, DSNs, secrets, and URLs, accepting "" usually defeats the purpose of validation.
Current behavior
import { cleanEnv, str, bool } from 'envalid'
process.env.API_KEY = ''
process.env.FEATURE_ENABLED = ''
const env = cleanEnv(process.env, {
API_KEY: str(),
FEATURE_ENABLED: bool(),
})Result:
API_KEY → '' (valid)
FEATURE_ENABLED → validation error ('' is not a valid boolean)
Expected behavior
Ideally, users should have an ergonomic way to treat empty strings as missing values, at least for required string variables.
Possible solutions
- Global option
Add a global cleanEnv option that treats empty strings as missing values for all validators:
cleanEnv(process.env, validators, {
treatEmptyStringsAsMissing: true,
})This would make "" behave the same as undefined.
- String-specific option (similar to Zod)
Add a non-empty mode for str().
Equivalent to Zod’s z.string().nonempty().
This is probably the least breaking option and keeps behavior explicit per variable.
- Boolean-specific option
Relax boolean parsing by ignoring empty strings.
bool({ ignoreEmptyStrings: true })My preference
I would prefer option 2 (str({ nonempty: true })) because it is explicit, non-breaking, and closely matches the API many users already know from validation libraries such as Zod.
A global option could also be valuable for teams that want stricter environment validation across an entire application.
Additional context
This issue commonly appears in Docker builds and container orchestration setups where variables are declared but left empty, for example:
In that situation, str() currently passes validation even though the application usually cannot function correctly with an empty API key.
Summary
envalidis designed specifically for environment-variable validation. In many deployment environments (Docker, Kubernetes, CI systems, .env files), an empty string is often effectively equivalent to “not provided”. For required configuration values such as API keys, DSNs, secrets, and URLs, accepting""usually defeats the purpose of validation.Current behavior
Result:
API_KEY → '' (valid)
FEATURE_ENABLED → validation error ('' is not a valid boolean)
Expected behavior
Ideally, users should have an ergonomic way to treat empty strings as missing values, at least for required string variables.
Possible solutions
Add a global cleanEnv option that treats empty strings as missing values for all validators:
This would make
""behave the same as undefined.Add a non-empty mode for str().
Equivalent to Zod’s
z.string().nonempty().This is probably the least breaking option and keeps behavior explicit per variable.
Relax boolean parsing by ignoring empty strings.
My preference
I would prefer option 2 (
str({ nonempty: true })) because it is explicit, non-breaking, and closely matches the API many users already know from validation libraries such as Zod.A global option could also be valuable for teams that want stricter environment validation across an entire application.
Additional context
This issue commonly appears in Docker builds and container orchestration setups where variables are declared but left empty, for example:
In that situation,
str()currently passes validation even though the application usually cannot function correctly with an empty API key.