Enum CliError 

pub enum CliError {
    ReadConfig {
        path: PathBuf,
        source: Error,
    },
    UnknownExtension {
        path: PathBuf,
    },
    ParseConfig {
        path: PathBuf,
        message: String,
    },
    MissingEnvVar {
        var: String,
        location: String,
    },
    ReadInterpolatedFile {
        path: PathBuf,
        source: Error,
    },
    InterpolatedFileTooLarge {
        path: PathBuf,
        max_bytes: u64,
    },
    UnknownInterpolationId {
        id: String,
        token: String,
    },
    MissingRecordField {
        id: String,
        path: String,
    },
    UnknownConnector {
        kind: &'static str,
        name: String,
        available: String,
    },
    UnknownStateStore {
        name: String,
        available: String,
    },
    UnknownTransform {
        name: String,
        available: String,
    },
    InvalidTransform {
        name: String,
        message: String,
    },
    InvalidConnectorConfig {
        kind: &'static str,
        name: String,
        message: String,
    },
    ScaffoldExists {
        path: PathBuf,
    },
    MissingEnvSelector {
        var: String,
    },
    EnvFileNotFound {
        path: PathBuf,
    },
    NoConfigOrFromEnv,
    EnvConflict {
        field: String,
        scalar_var: String,
        json_var: String,
    },
    InvalidEnvJson {
        var: String,
        message: String,
    },
    TransformIndexGap {
        missing: u32,
    },
    ReservedRowId {
        id: String,
    },
    DuplicateRowId {
        id: String,
    },
    UnknownParent {
        id: String,
        parent: String,
    },
    ParentCycle {
        ids: Vec<String>,
    },
    UnknownDependency {
        id: String,
        depends_on: String,
    },
    DependencyCycle {
        ids: Vec<String>,
    },
    DuplicateStateKey {
        id: String,
        state_key: String,
    },
    InvalidStateKey {
        id: String,
        state_key: String,
        reason: String,
    },
    PipelineHadFailures {
        count: usize,
    },
    MatrixAndNodesBothPresent,
    EdgeEndpointMissing {
        name: String,
        known: Vec<String>,
    },
    InvalidTopology {
        message: String,
    },
    TopologyHadFailures {
        count: usize,
    },
    UnknownDlqSinkKind {
        kind: String,
        context: String,
    },
    InvalidDlqBudget {
        field: &'static str,
    },
    UnknownTemplate {
        kind: &'static str,
        name: String,
        row_id: String,
        known: Vec<String>,
    },
    MissingTemplate {
        kind: &'static str,
        row_id: String,
    },
    DuplicateTemplate {
        kind: &'static str,
        name: String,
    },
    TransformsOnSink {
        name: String,
    },
    InheritTransformsOnSink {
        name: String,
    },
    InterpolationCycle {
        chain: Vec<String>,
    },
    CompositionCycle {
        chain: Vec<String>,
    },
    IncludeNotFound {
        path: PathBuf,
        referenced_by: PathBuf,
    },
    CompositionDepthExceeded {
        max: usize,
    },
    BadInclude {
        path: PathBuf,
        reason: String,
    },
    UnknownProfile {
        name: String,
        known: Vec<String>,
    },
    UnknownVarsRef {
        name: String,
        token: String,
    },
    UnknownTemplateRef {
        token: String,
        reason: String,
    },
    MissingParam {
        name: String,
        description: Option<String>,
    },
    UnknownParam {
        name: String,
        known: Vec<String>,
    },
    UnknownParamRef {
        name: String,
        token: String,
    },
    UnknownPipelineTemplate {
        id: String,
        version: Option<u32>,
    },
    UnknownAuthProvider {
        name: String,
        known: Vec<String>,
    },
    AuthProviderBuild {
        name: String,
        message: String,
    },
    NoMatchForSelector {
        flag: &'static str,
        token: String,
        available: Vec<String>,
    },
    UnknownStatus {
        value: String,
        available: Vec<String>,
    },
    UnknownTag {
        tag: String,
        available: Vec<String>,
    },
    UnknownIncludeParents {
        value: String,
    },
    SelectorsWithoutMatrix {
        flags: String,
    },
    EmptyRunSet {
        rows: Vec<String>,
    },
    RunSetMissingAncestors {
        pairs: Vec<String>,
        policy: &'static str,
    },
    Config(String),
    Faucet(FaucetError),
    Io(Error),
    Observability(String),
    Internal(String),
    SecretBackendDisabled {
        scheme: String,
    },
    SecretNotFound {
        scheme: String,
        reference: String,
    },
    SecretFetchFailed {
        scheme: String,
        reference: String,
        source: Box<dyn Error + Send + Sync>,
    },
    SecretAuthFailed {
        scheme: String,
        hint: String,
    },
    SecretNotJson {
        scheme: String,
        reference: String,
    },
    SecretFieldMissing {
        scheme: String,
        reference: String,
        field: String,
        available: Vec<String>,
    },
    SecretsRequireAsyncLoad,
    DoctorFailed {
        failed: usize,
    },
    TestsFailed {
        failed: usize,
    },
    BackfillFailed {
        failed: usize,
    },
    Serve(String),
    ScheduleOverlapForbidden,
}

Top-level error variants for the faucet binary.

Variants

ReadConfig

Failed to read a config file from disk.

Fields

path: PathBuf

source: Error

UnknownExtension

The config file extension is neither .yaml/.yml nor .json.

Fields

path: PathBuf

ParseConfig

Failed to parse the raw config text after interpolation.

Fields

path: PathBuf

message: String

MissingEnvVar

An ${env:VAR} reference could not be resolved.

Fields

var: String

location: String

ReadInterpolatedFile

A ${file:PATH} reference could not be read.

Fields

path: PathBuf

source: Error

InterpolatedFileTooLarge

Fields

path: PathBuf

max_bytes: u64

UnknownInterpolationId

A ${row_id.path} token referenced an unknown matrix row id at expand-time (or a typo’d load-time prefix that survived to record-time).

Fields

id: String

token: String

MissingRecordField

A ${row_id.path} resolved at record-time, but the dotted path doesn’t match any field in the parent record.

Fields

id: String

path: String

UnknownConnector

The named connector is unknown (or its feature flag is disabled in this build).

Fields

kind: &'static str

name: String

available: String

UnknownStateStore

The state-store type referenced in the config is unknown or not compiled in.

Fields

name: String

available: String

UnknownTransform

A transform type referenced in the config is not recognised.

Fields

name: String

available: String

InvalidTransform

The transform config block could not be deserialized into the expected shape.

Fields

name: String

message: String

InvalidConnectorConfig

A connector config object failed to deserialize.

Fields

kind: &'static str

name: String

message: String

ScaffoldExists

A scaffold target already exists.

Fields

path: PathBuf

MissingEnvSelector

The CLI was invoked with --from-env but the required selector env var (FAUCET_SOURCE or FAUCET_SINK) is unset.

Fields

var: String

EnvFileNotFound

An explicit --env-file path does not exist on disk.

Fields

path: PathBuf

NoConfigOrFromEnv

faucet run invoked with neither a config path nor --from-env, and auto-discovery found no faucet.{yaml,yml,json} in cwd.

EnvConflict

Both a scalar env var and its _JSON counterpart were set for the same field.

Fields

field: String

scalar_var: String

json_var: String

InvalidEnvJson

A *_JSON env var did not parse as JSON.

Fields

var: String

message: String

TransformIndexGap

FAUCET_TRANSFORM_<N> indices are not contiguous starting at 1.

Fields

missing: u32

ReservedRowId

A matrix row id collides with a load-time interpolation prefix.

Fields

id: String

DuplicateRowId

Two matrix rows declared the same id.

Fields

id: String

UnknownParent

A row’s parent: field names a row that doesn’t exist.

Fields

id: String

parent: String

ParentCycle

The parent chain contains a cycle.

Fields

ids: Vec<String>

UnknownDependency

A row’s depends_on: list names a row that doesn’t exist.

Fields

id: String

depends_on: String

DependencyCycle

The combined parent: + depends_on: graph contains a cycle.

Fields

ids: Vec<String>

DuplicateStateKey

Two parent records of the same matrix row resolved to the same parent_key value, producing a colliding state-key suffix.

Fields

id: String

state_key: String

InvalidStateKey

The state key derived from the pipeline name + row id (+ resolved parent-key value) is not a valid state-store key. Caught up front at unit construction rather than mid-run.

Fields

id: String

state_key: String

reason: String

PipelineHadFailures

One or more matrix invocations failed under on_error: continue.

Fields

count: usize

MatrixAndNodesBothPresent

Both pipeline.nodes (topology mode) and matrix: are non-empty. They are mutually exclusive: topology mode replaces the matrix.

EdgeEndpointMissing

A topology edge references a node id that doesn’t exist in nodes:.

Fields

name: String

known: Vec<String>

InvalidTopology

A topology graph-structure violation (arity, fan-out, join edges, cycle, reachability) reported by the core validator.

Fields

message: String

TopologyHadFailures

One or more topology sink nodes failed under on_error: continue.

Fields

count: usize

UnknownDlqSinkKind

DLQ sink kind is not registered (not compiled in or feature disabled).

Fields

kind: String

context: String

InvalidDlqBudget

DLQ budget field is set to zero (which is invalid; omit to mean ‘unlimited’).

Fields

field: &'static str

UnknownTemplate

A matrix row referenced a named template that doesn’t exist in pipeline.sources / pipeline.sinks (or the legacy default).

Fields

kind: &'static str

name: String

row_id: String

known: Vec<String>

MissingTemplate

A matrix row supplied no ref: and the legacy default template doesn’t exist either.

Fields

kind: &'static str

row_id: String

DuplicateTemplate

Both the legacy pipeline.source and pipeline.sources.default were declared (same for sinks). The default slot can only be defined once.

Fields

kind: &'static str

name: String

TransformsOnSink

A sink template carries a transforms: field, which only sources support.

Fields

name: String

InheritTransformsOnSink

A sink template carries inherit_transforms:, which only sources support.

Fields

name: String

InterpolationCycle

A cycle was detected resolving ${vars.X} / ${sources.X.PATH} / ${sinks.X.PATH} references at load time.

Fields

chain: Vec<String>

CompositionCycle

A config-composition include/extends chain contains a cycle.

Fields

chain: Vec<String>

IncludeNotFound

An extends/!include target file does not exist.

Fields

path: PathBuf

referenced_by: PathBuf

CompositionDepthExceeded

Composition nesting exceeded the safety cap (extends/!include loop guard).

Fields

max: usize

BadInclude

An !include tag had a non-string payload, an unsupported tag, or its target failed structural checks.

Fields

path: PathBuf

reason: String

UnknownProfile

--profile NAME (or FAUCET_PROFILE) named a profile not declared under profiles:.

Fields

name: String

known: Vec<String>

UnknownVarsRef

A ${vars.X} token referenced an undefined var.

Fields

name: String

token: String

UnknownTemplateRef

A ${sources.X.PATH} or ${sinks.X.PATH} token referenced an undefined template, or a dotted path that doesn’t resolve inside it.

Fields

token: String

reason: String

MissingParam

A params: entry declared required: true and the caller supplied no value (#444).

Fields

name: String

description: Option<String>

UnknownParam

A supplied param is not declared in the config’s params: block (#444). Rejected rather than ignored so a typo can never silently no-op.

Fields

name: String

known: Vec<String>

UnknownParamRef

A ${param.X} token referenced a param the config does not declare (#444).

Fields

name: String

token: String

UnknownPipelineTemplate

A pipeline-template id / version was not found in the registry (#444). Distinct from CliError::UnknownTemplate, which is about a pipeline.sources / pipeline.sinks connector template.

Fields

id: String

version: Option<u32>

UnknownAuthProvider

A connector’s auth: { ref } named a provider not declared in the top-level auth: catalog.

Fields

name: String

known: Vec<String>

AuthProviderBuild

A top-level auth: provider spec failed to build.

Fields

name: String

message: String

NoMatchForSelector

A --select/--only/--skip token matched no matrix row id (#370). Guards against typos silently producing a partial or empty run.

Fields

flag: &'static str

token: String

available: Vec<String>

UnknownStatus

A --status <tier> value is not one of the readiness-ladder tiers (#371).

Fields

value: String

available: Vec<String>

UnknownTag

A --tag <t> value matches no row’s tags (#376). Typo protection.

Fields

tag: String

available: Vec<String>

UnknownIncludeParents

A --include-parents <policy> value is not off/eligible/all (#377).

Fields

value: String

SelectorsWithoutMatrix

Matrix-only selectors were passed for a config with no matrix: (single anonymous invocation) — nothing to select among (#370/#376).

Fields

flags: String

EmptyRunSet

The resolved run set is empty after status gating / tag narrowing / skip (#371). Not a silent no-op — names each row’s status and how to include.

Fields

rows: Vec<String>

RunSetMissingAncestors

A run-set row structurally depends on an ancestor that is not in the run set, under the active include_parents policy (#377). Lists every offending dependent → ancestor (edge) pair.

Fields

pairs: Vec<String>

policy: &'static str

Config(String)

A config-level validation failure that isn’t covered by a more specific variant (e.g. an invalid quality: block, or a quality check that requires a DLQ when none is configured).

Faucet(FaucetError)

Pass-through for failures bubbling up from faucet-core or a connector.

Io(Error)

Pass-through I/O error.

Observability(String)

Observability stack (Prometheus / tracing) failed to install.

Internal(String)

An internal invariant was violated (a bug). Surfaced instead of silently producing a partial result.

SecretBackendDisabled

A secret-manager directive used a scheme whose backend feature was not compiled into this binary.

Fields

scheme: String

SecretNotFound

The secrets manager has no secret at the given reference.

Fields

scheme: String

reference: String

SecretFetchFailed

The secret fetch failed (network / API error).

Fields

scheme: String

reference: String

source: Box<dyn Error + Send + Sync>

SecretAuthFailed

No ambient credentials were available for the backend.

Fields

scheme: String

hint: String

SecretNotJson

A #field selector was used on a secret that is not JSON.

Fields

scheme: String

reference: String

SecretFieldMissing

A #field selector named a key absent from the secret JSON.

Fields

scheme: String

reference: String

field: String

available: Vec<String>

SecretsRequireAsyncLoad

A secret directive was found while loading via the synchronous path.

DoctorFailed

One or more faucet doctor preflight probes failed. The checklist is printed by the command; main maps this to an exit code equal to the failed-probe count (clamped to 255).

Fields

failed: usize

TestsFailed

One or more faucet test cases failed. The report is printed by the command; main maps this to an exit code equal to the failed-case count (clamped to 255).

Fields

failed: usize

BackfillFailed

One or more faucet backfill units failed. The per-unit report is printed by the command (progress is already durably recorded, so --resume retries only the failures); main maps this to an exit code equal to the failed-unit count (clamped to 255).

Fields

failed: usize

Serve(String)

A faucet serve startup or runtime failure (bind, auth gate, etc.).

ScheduleOverlapForbidden

overlap_policy: forbid saw a tick fire while a run was still in flight.

Trait Implementations

impl Debug for CliError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for CliError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for CliError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for CliError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<FaucetError> for CliError

fn from(source: FaucetError) -> Self

Converts to this type from the input type.

impl From<InstallError> for CliError

fn from(e: InstallError) -> Self

Converts to this type from the input type.