Enum ConfigError 

pub enum ConfigError {
    Env(String),
    FileOpen {
        path_to_open: String,
        io_error: Error,
    },
    FileRead {
        path_to_read: String,
        io_error: Error,
    },
    Incompatible {
        kind: IncompatibilityKind,
        object: ObjectKind,
        id: String,
    },
    InvalidFrontendConfig(String),
    InvalidPath(PathBuf),
    ListenerAddressAlreadyInUse(SocketAddr),
    ListenerAlreadyDeclared(ListenerKey),
    ListenerProtocolMismatchOnAddress(SocketAddr),
    ListenerInterface {
        address: SocketAddr,
        error: InterfaceError,
    },
    Missing(MissingKind),
    NoFileParent(String),
    SaveStatePath(String),
    SocketPathError(String),
    DeserializeToml(String),
    WrongFrontendProtocol(ListenerProtocol),
    WrongListenerProtocol {
        expected: ListenerProtocol,
        found: Option<ListenerProtocol>,
    },
    InvalidAlpnProtocol(String),
    InvalidAffinityKey {
        cluster_id: String,
        reason: &'static str,
    },
    InvalidShuffleSharding {
        cluster_id: String,
        reason: &'static str,
    },
    InvalidMaxConnectionAttempts {
        cluster_id: Option<String>,
        value: u32,
        reason: &'static str,
    },
    InvalidBackendUnixPath {
        cluster_id: String,
        address: SocketAddr,
        reason: &'static str,
    },
    InvalidHealthCheck {
        cluster_id: String,
        reason: &'static str,
    },
    InvalidSubnetPrefix {
        key: &'static str,
        family: &'static str,
        value: u32,
        maximum: u32,
    },
    InvalidCommandSocketMode {
        value: String,
        reason: &'static str,
    },
    DisableHttp11WithHttp11Alpn {
        address: String,
    },
    BufferSizeTooSmallForH2 {
        buffer_size: u64,
        minimum: u64,
        listeners: usize,
    },
    CommandBufferSizeExceedsMax {
        command_buffer_size: u64,
        max_command_buffer_size: u64,
    },
    H2ThresholdBelowMinimum {
        address: String,
        key: &'static str,
        value: u64,
        minimum: u64,
    },
    InvalidRedirectPolicy(String),
    InvalidRedirectScheme(String),
    InvalidHeaderPosition {
        index: usize,
        position: String,
    },
    InvalidHeaderBytes {
        index: usize,
        field: &'static str,
    },
    InvalidHeaderPredicate {
        index: usize,
        reason: &'static str,
    },
    HstsEnabledRequired(String),
    HstsOnPlainHttp(String),
    ClientAuthOnNonHttps(String),
    ClientAuthModeMissing(String),
    InvalidSniPattern {
        sni: String,
    },
    NonAsciiSniPattern {
        sni: String,
    },
    AlpnWithoutSni {
        address: SocketAddr,
    },
    TcpFrontendAlpnOverlap {
        address: SocketAddr,
        sni: Option<String>,
        protocol: String,
    },
    TcpFrontendMultipleAlpnCatchAll {
        address: SocketAddr,
        sni: Option<String>,
    },
    TcpListenerMixesSniAndNoSni {
        address: SocketAddr,
    },
    SniPrereadTimeoutExceedsFrontTimeout {
        address: SocketAddr,
        sni_preread_timeout: u32,
        front_timeout: u32,
    },
    SniPrereadMaxBytesExceedsBufferSize {
        address: SocketAddr,
        sni_preread_max_bytes: u32,
        buffer_size: u64,
    },
    SniPrereadMaxBytesTooSmall {
        address: SocketAddr,
        sni_preread_max_bytes: u32,
        minimum: u32,
    },
    BackendAddressResolution {
        cluster_id: String,
        address: String,
        reason: String,
    },
}

Variants

Env(String)

FileOpen

Fields

path_to_open: String

io_error: Error

FileRead

Fields

path_to_read: String

io_error: Error

Incompatible

Fields

kind: IncompatibilityKind

object: ObjectKind

id: String

InvalidFrontendConfig(String)

InvalidPath(PathBuf)

ListenerAddressAlreadyInUse(SocketAddr)

ListenerAlreadyDeclared(ListenerKey)

ListenerProtocolMismatchOnAddress(SocketAddr)

ListenerInterface

Fields

address: SocketAddr

error: InterfaceError

Missing(MissingKind)

NoFileParent(String)

SaveStatePath(String)

SocketPathError(String)

DeserializeToml(String)

WrongFrontendProtocol(ListenerProtocol)

WrongListenerProtocol

Fields

expected: ListenerProtocol

found: Option<ListenerProtocol>

InvalidAlpnProtocol(String)

InvalidAffinityKey

A cluster’s affinity_header / affinity_cookie breaks validate_affinity_key, or is set on a TCP cluster.

Fields

cluster_id: String

reason: &'static str

InvalidShuffleSharding

A cluster’s shuffle-sharding knobs break validate_shuffle_sharding.

Fields

cluster_id: String

reason: &'static str

InvalidMaxConnectionAttempts

A max_connection_attempts, global (cluster_id is None) or of a cluster, breaks validate_max_connection_attempts.

Fields

cluster_id: Option<String>

value: u32

reason: &'static str

InvalidBackendUnixPath

A backend’s unix_path breaks parse_backend_unix_path, shares its identity address with another backend of the cluster, or sits in a UDP cluster.

Fields

cluster_id: String

address: SocketAddr

reason: &'static str

InvalidHealthCheck

A cluster’s health_check block has an unparsable accepted_statuses entry or breaks validate_health_check_config.

Fields

cluster_id: String

reason: &'static str

InvalidSubnetPrefix

subnet_ipv4_prefix / subnet_ipv6_prefix is outside the bit width of its address family. Rejected rather than clamped: a silently narrowed mask would enforce a different policy than the one written in the file, and the operator would have no way to tell from the config which one is in force.

Fields

key: &'static str

family: &'static str

value: u32

maximum: u32

InvalidCommandSocketMode

command_socket_mode is not an octal permission string within MAX_COMMAND_SOCKET_MODE. See parse_command_socket_mode.

Fields

value: String

reason: &'static str

DisableHttp11WithHttp11Alpn

disable_http11 = true and alpn_protocols containing "http/1.1" are mutually exclusive: the proxy advertises http/1.1 to peers, then refuses every connection that negotiates it. The combination is a self-DoS at handshake time. Either drop http/1.1 from alpn_protocols or unset disable_http11.

Fields

address: String

BufferSizeTooSmallForH2

buffer_size is below the H2 minimum (16 393 bytes) but at least one HTTPS listener advertises h2 in its ALPN list. The H2 mux requires 16 384-byte frame payload + 9-byte header to fit in a single kawa buffer; smaller values deadlock streams that carry full-size frames. Either raise buffer_size to ≥ 16 393 or remove h2 from the affected listeners’ alpn_protocols.

Fields

buffer_size: u64

minimum: u64

listeners: usize

CommandBufferSizeExceedsMax

command_buffer_size is greater than max_command_buffer_size. The command channel (command/src/channel.rs) allocates its initial buffer at command_buffer_size and must never let it exceed max_command_buffer_size — every growth/shrink path on that channel reasons against that ceiling. Rejected at load rather than silently clamped, so the operator sees which of the two keys to fix instead of the mistake being rewritten out from under them (sozu-proxy/sozu#1416).

Fields

command_buffer_size: u64

max_command_buffer_size: u64

H2ThresholdBelowMinimum

An H2 listener knob was set below the minimum the runtime can honour. Every flood-detection threshold needs >= 1: check_flood (lib/src/protocol/mux/h2_flood_detector.rs) compares count > threshold, so 0 does not disable the check, it makes the first event the counter sees a violation. h2_stream_shrink_ratio needs >= 2 for the same reason its runtime .max(2) exists.

What that costs depends on which counter the key guards, and the error text says so rather than promising the worst case for all of them:

• h2_max_header_list_size and h2_max_header_fields are also the HPACK decode budget lib/src/protocol/mux/pkawa.rs’s decode_headers_with_budget enforces. At 0 the first header field of every block already exceeds it (name + value + the 32-octet RFC 9113 §6.5.2 overhead), so every request on the listener is refused with ENHANCE_YOUR_CALM. Immediate and universal. The frame it arrives in depends on the request: a header block that fits one HEADERS frame is refused per stream (pkawa.rs’s Err((EnhanceYourCalm, false)) → reset_stream), while one that spans CONTINUATION frames takes the whole connection down — record_continuation_frame lifts accumulated_header_size above the zero threshold and check_flood_or_return! (lib/src/protocol/mux/h2.rs) escalates to GOAWAY(ENHANCE_YOUR_CALM) before the explicit size test below it. h2_max_header_table_size is NOT in this class: 0 only zeroes the HPACK encoder’s dynamic table.
• The per-window and lifetime frame counters only move when a client sends the frame they count. h2_max_rst_stream_per_window = 0 is harmless to a connection that never sends RST_STREAM — 0 > 0 is false — and fatal to the first one that does.
• h2_max_concurrent_streams and h2_stream_shrink_ratio are not flood counters at all: H2ConnectionConfig::new (lib/src/protocol/mux/h2.rs) promotes an out-of-range value to the floor behind a warn!, which is the silent rewrite this error exists to replace.

Rejected at config load rather than silently clamped, so the operator sees which key to fix instead of the mistake being rewritten out from under them. UpdateHttp(s)Listener already refuses the same values via validate_h2_flood_knobs_http/_https (command/src/state.rs); this is the matching gate on the config-file / sozu ctl add listener path (sozu-proxy/sozu#1418).

Fields

address: String

key: &'static str

value: u64

minimum: u64

InvalidRedirectPolicy(String)

redirect = "<value>" on a frontend used a value the parser doesn’t recognise. Accepted values are forward, permanent, unauthorized, silent_close (case-insensitive).

InvalidRedirectScheme(String)

redirect_scheme = "<value>" on a frontend used a value the parser doesn’t recognise. Accepted values are use-same, use-http, use-https (case-insensitive).

InvalidHeaderPosition

A [[clusters.<id>.frontends.headers]] entry carried an unknown position value. Accepted values are request, response, both (case-insensitive).

Fields

index: usize

position: String

InvalidHeaderBytes

A [[clusters.<id>.frontends.headers]] entry contains a forbidden byte (NUL, CR, LF, or another C0 control) in its key or value. Accepting these would produce HTTP request/response splitting on the wire (CWE-113) — the worker’s H2 emission path filters them at runtime, but the H1 path serialises raw, so we reject at config-load time as a defense in depth.

Fields

index: usize

field: &'static str

InvalidHeaderPredicate

A header_predicates entry on a frontend is not a usable routing condition (sozu-proxy/sozu#1253); reason names what is wrong. The regex grammar of a regex predicate is checked later, by the router, exactly as a path_type = "regex" path is.

Fields

index: usize

reason: &'static str

HstsEnabledRequired(String)

An [hsts] block populated max_age, include_subdomains, or preload but did not set enabled. The TOML representation requires enabled to be present whenever the block is — that single field disambiguates “preserve current” / “explicit disable” / “enable” on hot-reconfig partial updates.

HstsOnPlainHttp(String)

An [hsts] block on an HTTP-only listener or frontend. RFC 6797 §7.2 forbids emitting Strict-Transport-Security over plaintext HTTP; sozu rejects the configuration at load time so the non-conformant policy never ships to a worker.

ClientAuthOnNonHttps(String)

A client-certificate-authentication (mTLS) field was set on a non-HTTPS listener. Client auth is a TLS-termination control; HTTP/TCP/UDP listeners discard it, so sozu rejects it at load time rather than silently starting an unauthenticated listener.

ClientAuthModeMissing(String)

An HTTPS listener names client CA or CRL files but no client_auth mode. The mode defaults to none, which ignores those files, so the listener would start without the client authentication they suggest.

InvalidSniPattern

A TCP frontend’s hostname (mapped to the wire sni field) is neither an exact hostname nor a single leading *. wildcard label (sozu-proxy/sozu#1279). Rejects *.*.example.com, an embedded * anywhere but the leading label, an empty label, and any / — never valid in a hostname, and a leftmost /.../ label would otherwise be inserted into the pattern_trie route table as a REGEX segment.

Fields

sni: String

NonAsciiSniPattern

A TCP frontend’s SNI pattern contains non-ASCII characters. On-wire SNI is always an ASCII A-label (RFC 6066 §3 / IDNA), so a Unicode U-label in the config would load fine but never match any ClientHello — a silent routing failure. Rejected loudly until IDNA normalization is supported at config-load; the operator must write the punycode A-label form instead.

Fields

sni: String

AlpnWithoutSni

A TCP frontend set alpn but left hostname (mapped to the wire sni field) unset. An ALPN matcher only ever gets consulted from within the SNI-scoped preread route table; a frontend with no sni installs the worker’s raw no-SNI catch-all path instead (TcpListener::cluster_id), which never looks at alpn at all – the configured protocol list would silently never be enforced. Reject at config-load rather than mis-routing every connection through unconditionally.

Fields

address: SocketAddr

TcpFrontendAlpnOverlap

Two TCP frontends on the same (address, sni) advertise an overlapping ALPN protocol. Routing on a listener must be deterministic: if both frontends could match the same ClientHello, which cluster receives the connection would depend on iteration order rather than configuration.

Fields

address: SocketAddr

sni: Option<String>

protocol: String

TcpFrontendMultipleAlpnCatchAll

More than one TCP frontend on the same (address, sni) left alpn empty. An empty alpn is the catch-all match for that sni; two catch-alls on the same (address, sni) are as ambiguous as two frontends sharing an explicit protocol.

Fields

address: SocketAddr

sni: Option<String>

TcpListenerMixesSniAndNoSni

A TCP listener address is targeted by both a no-SNI frontend and at least one SNI-scoped frontend. An SNI-enabled listener prereads the ClientHello before choosing a backend; a raw-TCP fallback frontend with no SNI to match against would be unreachable for any client that doesn’t send SNI, and ambiguous for any that does, so the two shapes cannot share a listener.

Fields

address: SocketAddr

SniPrereadTimeoutExceedsFrontTimeout

sni_preread_timeout on a TCP listener exceeds that listener’s front_timeout. The preread phase is bounded by the frontend’s own inactivity timeout, so a preread budget longer than the timeout that would kill the connection anyway can never fully elapse — it is either a config mistake or silently dead configuration.

Fields

address: SocketAddr

sni_preread_timeout: u32

front_timeout: u32

SniPrereadMaxBytesExceedsBufferSize

sni_preread_max_bytes on a TCP listener targeted by at least one SNI frontend exceeds the global buffer_size. The preread buffer is carved out of the same per-session buffer the proxy uses for relaying, so a preread ceiling above buffer_size can never be reached in practice and signals a misconfiguration.

Fields

address: SocketAddr

sni_preread_max_bytes: u32

buffer_size: u64

SniPrereadMaxBytesTooSmall

sni_preread_max_bytes on a TCP listener targeted by at least one SNI frontend is below MIN_SNI_PREREAD_MAX_BYTES. 0 in particular makes the preread shell issue zero-length reads that can never make progress – the session spins until the event-loop iteration guard (MAX_LOOP_ITERATIONS) trips instead of ever completing a preread decision. The floor is a full TLS record header (1-byte ContentType + 2-byte ProtocolVersion + 2-byte length, RFC 8446 §5.1): below that, the shell cannot even learn how many more bytes to wait for.

Fields

address: SocketAddr

sni_preread_max_bytes: u32

minimum: u32

BackendAddressResolution

A backend address of the configuration file is neither a socket address nor a host:port that resolves to at least one address (sozu-proxy/sozu#347). Names are resolved once, when the file is loaded at startup or by sozu reload --file.

Fields

cluster_id: String

address: String

reason: String

Trait Implementations

impl Debug for ConfigError

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

Formats the value using the given formatter.

impl Display for ConfigError

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

Formats the value using the given formatter.

impl Error for ConfigError

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.