Enum PreFlightError 

pub enum PreFlightError {
    BinaryNotFound {
        path: PathBuf,
    },
    ArgvExceedsArgMax {
        total_bytes: usize,
        arg_max: usize,
    },
    McpConfigInlineJsonRejected(String),
    McpConfigPathMissing {
        path: PathBuf,
    },
    McpConfigPathInvalidJson {
        path: PathBuf,
        error: String,
    },
    WalkUpMcpJsonInvalid {
        path: PathBuf,
        error: String,
    },
    OutputBufferTooSmall {
        expected: usize,
        configured: usize,
    },
    ClaudeConfigDirNotEmpty {
        path: PathBuf,
        reason: &'static str,
    },
}

Structured errors from the pre-flight gate. Each variant carries the data needed for an operator to diagnose without re-running.

thiserror produces the Display impl that AppError::PreFlightFailed captures into the detail field for i18n.

Variants

BinaryNotFound

Binary at path does not exist on the filesystem.

Fields

path: PathBuf

ArgvExceedsArgMax

Total bytes of argv (binary + args + separators) exceed ARG_MAX - 4096. Spawn would fail with E2BIG post-fork.

Fields

total_bytes: usize

arg_max: usize

McpConfigInlineJsonRejected(String)

--mcp-config '{...}' was passed literally as the inline JSON. Claude Code 2.1.177+ expects a filepath. Caller should use the suggested_tempfile (already written with empty mcpServers map).

McpConfigPathMissing

--mcp-config <PATH> was passed but the path does not exist.

Fields

path: PathBuf

McpConfigPathInvalidJson

--mcp-config <PATH> was passed but the file is not valid JSON.

Fields

path: PathBuf

error: String

WalkUpMcpJsonInvalid

.mcp.json walk-up found an invalid file at path. Override CLAUDE_CONFIG_DIR to an empty directory to suppress walk-up.

Fields

path: PathBuf

error: String

OutputBufferTooSmall

Caller’s expected output exceeds the documented JSON parser cap. The downstream parser truncates silently above this size.

Fields

expected: usize

configured: usize

ClaudeConfigDirNotEmpty

CLAUDE_CONFIG_DIR is set and settings.json declares active mcpServers. Claude Code would load them and defeat --strict-mcp-config --mcp-config <empty>. Hooks are NOT flagged here because the spawners pass --settings '{"hooks":{}}' which overrides the user-level hooks at the CLI invocation boundary; MCP servers are NOT overridden by any flag we pass, so they are the only class of settings.json entry that can leak into the subprocess.

Fields

path: PathBuf

reason: &'static str

Trait Implementations

impl Debug for PreFlightError

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

Formats the value using the given formatter.

impl Display for PreFlightError

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

Formats the value using the given formatter.

impl Error for PreFlightError

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<PreFlightError> for AppError

Bridges the structured PreFlightError produced by the pre-flight validation gate (v1.0.87, ADR-0045) into the unified AppError envelope. Lets spawners use the ? operator instead of hand-rolling AppError::PreFlightFailed { source: ... } at every call site, and keeps the variant alive as the canonical exit code 16 path rather than the dead code it was at v1.0.87.

fn from(source: PreFlightError) -> Self

Converts to this type from the input type.