Error Handling

Typed, actionable, and secret-safe environment and resolver failures.

Validation failures

EnvValidationError.issues is a frozen discriminated union:

type EnvValidationIssue =
  | {
      readonly _tag: "MissingVariable";
      readonly key: string;
      readonly schemaIdentifier?: string;
      readonly sensitive: boolean;
    }
  | {
      readonly _tag: "InvalidVariable";
      readonly key: string;
      readonly schemaIdentifier?: string;
      readonly sensitive: boolean;
    };

Rejected values are never retained. Messages name the affected variable, describe the expected format, and provide the next action.

Configuration failures

EnvConfigurationError covers invalid definitions that JavaScript callers can still construct despite TypeScript checks, including:

• a missing client runtimeEnv;
• fromResolver or redaction in a client fragment;
• duplicate winning definitions that map to the same runtime name;
• shared values shadowing runtime properties;
• malformed resolver results.

Resolver failures

Provider adapters use tagged failures in the Effect error channel:

• ResolverConfigurationError
• ResolverInitializationError
• ResolverRequestFailed
• ResolverResponseDecodeFailed

Messages never include runtime values, secret references, provider responses, credentials, or arbitrary thrown causes.

Runtime access failures

ServerEnvironmentAccessError is returned through the server Effect’s typed error channel when Envil cannot prove that the caller is running server-side. No server runtime value or resolver is read before this check.

EnvironmentAccessError is raised by the output Proxy when code bypasses TypeScript and reads a value outside the materialized target:

"DATABASE_URL" is not available in the client environment.
Declare it in a client fragment if it is public, or read it through
appEnv.server from server code.

The message deliberately does not confirm whether the requested name exists in the server definition. This keeps the client Proxy independent from server-key metadata.