Errors

When envapt rejects a value or a configuration, it throws an EnvaptError. The error carries a numeric code from the EnvaptErrorCodes enum, so you can branch on the exact cause.

try {
    .('DATABASE_URL');
} catch () {
    if ( instanceof ) {
        .code;              
EnvaptError.code: EnvaptErrorCodes
The
EnvaptErrorCodes
value identifying what failed.
        if (. === .) {
            .?.(() => .(.));
        }
    }
}

The error shape

EnvaptError extends Error with:

code: the EnvaptErrorCodes member.
name: set to `EnvaptError [<code>]` (e.g. EnvaptError [305]).
message: a human-readable description.
issues: the validator's issue list, populated only for SchemaValidationFailed (208); undefined for every other code.
cause: the original error when one is chained, used by SchemaThrew (209).

Code	Name	Thrown when
101	`InvalidFallback`	A fallback value is invalid for the converter (for example, a non-array fallback for an array converter).
102	`InvalidFallbackType`	The fallback value's type doesn't match the converter's return type.
103	`ArrayFallbackElementTypeMismatch`	An array fallback contains an element of the wrong type.
104	`FallbackConverterTypeMismatch`	The fallback is not a valid value for the converter (wrong type, out of range, or malformed).
105	`MalformedTimeFallback`	A time-string fallback isn't `<number><unit>` (for example `90m`).

Code	Name	Thrown when
201	`InvalidArrayConverterType`	The `Converters.array` configuration is malformed.
202	`InvalidBuiltInConverter`	An unknown built-in converter token is used.
203	`InvalidCustomConverter`	A custom converter is not a function.
204	`InvalidConverterType`	The converter type is not recognized.
205	`PrimitiveCoercionFailed`	Coercing a fallback through a primitive constructor fails.
206	`ArrayElementConversionFailed`	An array element fails to convert to the configured element type.
207	`EmptyArrayElement`	Strict mode only: an array element is empty or whitespace.
208	`SchemaValidationFailed`	A Standard Schema returns issues for a non-empty value. The only code that populates `issues`.
209	`SchemaThrew`	A schema's `validate` itself throws. The original error is on `cause`.

Code	Name	Thrown when
301	`MissingDelimiter`	An array converter is missing its delimiter.
302	`InvalidUserDefinedConfig`	A bad decorator/options combination: `required` with `fallback`, `schema` with `converter`, a non-`StandardSchemaV1` `schema`, an async schema, or an invalid debug level.
303	`EnvFilesNotFound`	A configured `.env` path (via `envPaths` or `configureProfiles`) doesn't exist.
304	`InvalidKeyInput`	No key, a non-string key, or an empty-string key was passed.
305	`MissingEnvValue`	A required value is missing or empty, or whitespace-only under strict: `require`, `{ required: true }`, a schema with no fallback, or an unresolved template under strict mode.
306	`FileApiUnsupported`	On the portable build: a file-only API (`envPaths`, `baseDir`, `envFileOptions`, `configureProfiles`, `resetProfiles`) is called and `Envapter.fileApiMode = 'throw'` (the default warns once and no-ops). On the node build: a non-filesystem source is bound and a file API is called. See Sources.
307	`NoSourceBound`	A value is read before a source is bound with `Envapter.useSource`. Cannot occur on Node, where the source is bound on import.
308	`InvalidMergedSource`	`merge` is called with no members, or with more than one filesystem-backed source.

issues is set only for SchemaValidationFailed (208), so you can read error.issues after checking error.code === EnvaptErrorCodes.SchemaValidationFailed without a cast. See Standard Schema for where 208 and 209 come from.

The error shape

Codes

Fallback (101-105)

Converter (201-209)

Configuration and lookup (301-308)

On this page