(err: SourceError | Schema.SchemaError): Config<never>Creates a config that always fails with the given error.
When to use
Use when you need to re-raise a specific config error, such as inside orElse.
export function function fail(
err: SourceError | Schema.SchemaError
): Config<never>
Creates a config that always fails with the given error.
When to use
Use when you need to re-raise a specific config error, such as inside
orElse
.
fail(err: SourceError | Schema.SchemaErrorerr: class SourceErrorclass SourceError {
name: string;
message: string;
stack: string;
cause: unknown;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
_tag: Tag;
}
Typed error indicating that a configuration source could not be read.
When to use
Use when you need to report that a custom provider's underlying store is
unreachable or produced an I/O error while reading configuration data.
Gotchas
Do not use SourceError for "key not found". That case is represented by
returning undefined from load.
Example (Failing with a SourceError)
import { ConfigProvider, Effect } from "effect"
const provider = ConfigProvider.make((_path) =>
Effect.fail(
new ConfigProvider.SourceError({ message: "connection refused" })
)
)
SourceError | import SchemaSchema.class SchemaError
export SchemaError
class SchemaError {
message: string;
toString: () => string;
name: string;
stack: string;
cause: unknown;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toJSON: () => unknown;
_tag: Tag;
issue: SchemaIssue.Issue;
}
Error thrown (or returned as the error channel value) when schema decoding
or encoding fails.
Details
The issue field contains a structured
SchemaIssue.Issue
tree describing
every validation failure, including the path to the problematic value,
expected types, and actual values received. message renders the issue tree
as a human-readable string.
Use
isSchemaError
to narrow an unknown value to SchemaError.
Example (Catching a SchemaError)
import { Schema } from "effect"
try {
Schema.decodeUnknownSync(Schema.Number)("not a number")
} catch (err) {
if (Schema.isSchemaError(err)) {
console.log(err.message)
// Expected number, actual "not a number"
}
}
SchemaError) {
return function make<T>(
parse: (
provider: ConfigProvider.ConfigProvider,
pathPrefix: Path
) => Effect.Effect<T, ConfigError>
): Config<T>
import EffectEffect.const fail: <E>(
error: E
) => Effect<never, E>
Creates an Effect that represents a recoverable error.
When to use
Use to explicitly signal a recoverable error in an Effect.
Details
The error keeps propagating unless it is handled. You can handle tagged
errors with functions like
catchTag
or
catchTags
.
Example (Creating a failed effect)
import { Data, Effect } from "effect"
class OperationFailedError extends Data.TaggedError("OperationFailedError")<{}> {}
// ┌─── Effect<never, OperationFailedError, never>
// ▼
const failure = Effect.fail(
new OperationFailedError()
)
fail(new constructor ConfigError(cause: SourceError | Schema.SchemaError): ConfigErrorRepresents the error type produced when config loading or validation fails.
When to use
Use when you need to inspect config loading or validation failures.
Details
Wraps either:
- A
SourceError — the provider could not read data (I/O failure).
- A
SchemaError — the data was found but did not match the schema
(wrong type, out of range, missing key, etc.).
ConfigError(err: SourceError | Schema.SchemaErrorerr)))
}