non-filesystem OS function reached filesystem parser

Error message

non-filesystem OS function reached filesystem parser

What it means

An `unreachable!()` panic in monty-fs's OS-call dispatcher: `fs_request_from_call` is only supposed to receive filesystem-related `OsFunctionCall`s, but a non-filesystem variant (Getenv, GetEnviron, DateToday, DateTimeNow) reached it. This means dispatch upstream routed an OS call to the filesystem parser incorrectly.

Source

Thrown at crates/monty-fs/src/dispatch.rs:171

            path: a.path,
            parents: a.parents,
            exist_ok: a.exist_ok,
        },
        OsFunctionCall::Unlink(path) => FsRequest::Unlink { path },
        OsFunctionCall::Rmdir(path) => FsRequest::Rmdir { path },
        OsFunctionCall::Iterdir(path) => FsRequest::Iterdir { path },
        OsFunctionCall::Stat(path) => FsRequest::Stat { path },
        OsFunctionCall::Rename(a) => FsRequest::Rename { src: a.src, dst: a.dst },
        OsFunctionCall::Resolve(path) => FsRequest::Resolve { path },
        OsFunctionCall::Absolute(path) => FsRequest::Absolute { path },
        OsFunctionCall::Open(a) => FsRequest::Open {
            path: a.path,
            mode: a.mode,
        },
        OsFunctionCall::Getenv(_)
        | OsFunctionCall::GetEnviron
        | OsFunctionCall::DateToday
        | OsFunctionCall::DateTimeNow(_) => unreachable!("non-filesystem OS function reached filesystem parser"),
    }
}

/// Routes a parsed request to the correct backend for the mount mode.
pub(super) fn execute(
    request: FsRequest,
    ctx: &mut MountContext<'_>,
    mode: &mut MountMode,
) -> Result<MontyObject, MountError> {
    if request.is_write() && matches!(mode, MountMode::ReadOnly) {
        Err(MountError::ReadOnly(request.primary_path().to_owned()))
    } else {
        match mode {
            MountMode::ReadWrite | MountMode::ReadOnly => direct::execute(request, ctx),
            MountMode::OverlayMemory(state) => overlay::execute(request, ctx, state),
        }
    }
}

View on GitHub (pinned to adc986b362)

Solutions

Fix the upstream dispatcher so non-filesystem OsFunctionCall variants are handled before reaching fs_request_from_call.
Add the new variant to the unreachable list (or better, to its proper handler) when extending OsFunctionCall.
Check that all host callers (pool, CLI, bindings) route os calls through the central dispatch function.

Example fix

// before
OsFunctionCall::Getenv(_) => unreachable!(...);
// after (in the dispatcher, before fs parsing)
OsFunctionCall::Getenv(a) => return handle_getenv(a),
OsFunctionCall::DateToday => return handle_date_today(),

Defensive patterns

Strategy: validation

Validate before calling

// Central dispatcher: route by category before fs parsing
match call {
    OsFunctionCall::Getenv(_) | OsFunctionCall::GetEnviron
    | OsFunctionCall::DateToday | OsFunctionCall::DateTimeNow(_) => handle_non_fs(call),
    _ => handle_fs(call),
}

Type guard

fn is_fs_call(call: &OsFunctionCall) -> bool {
    !matches!(call, OsFunctionCall::Getenv(_) | OsFunctionCall::GetEnviron
        | OsFunctionCall::DateToday | OsFunctionCall::DateTimeNow(_))
}

Prevention

When adding an OsFunctionCall variant, update every dispatcher match arm, including fs_request_from_call's unreachable list.
Route all host os-call servicing through one central dispatch function.
Add dispatch tests for each OsFunctionCall variant.

When it happens

Trigger: Servicing an `OsFunctionCall` via `MountTable::handle_os_call` when the top-level dispatcher fails to filter out `Getenv`/`GetEnviron`/`DateToday`/`DateTimeNow` and passes them into `fs_request_from_call`.

Common situations: Hit when a new OsFunctionCall variant is added and not added to the dispatcher's non-filesystem filter, or when a host binding routes os callbacks to the wrong handler.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of pydantic/monty@adc986b362 (2026-09-13). Data as JSON: /api/errors/fd752a29bcfc63a4. Report an issue: GitHub.