How to Fix: `wasi::http::outgoing_handler::handle` crashes `wasmtime` instead of returning an error

wasmtime crashing inside wasi::http::outgoing_handler::handle is a contract-validation bug: the host should reject an invalid OutgoingRequest and return an error, not abort execution when required fields like path_with_query are missing.

Problem Overview

The issue appears when code calls wasi::http::outgoing_handler::handle with an invalid request object. A common reproducer is constructing an OutgoingRequest without setting path_with_query. Instead of returning a normal WASI HTTP error, wasmtime crashes.

In practical terms, this means the runtime is not defensively validating guest-provided state before using it. For embedders and application developers, the expected behavior is straightforward: malformed request input should produce a recoverable error path, allowing the guest or host application to handle it cleanly.

A minimal repro looks like this:

use wasi::http::outgoing_handler::handle;
use wasi::http::types::{Fields, OutgoingRequest, Scheme};

fn trigger_crash() {
    let headers = Fields::new();
    let req = OutgoingRequest::new(headers);

    req.set_scheme(Some(&Scheme::Https)).unwrap();
    req.set_authority(Some("example.com")).unwrap();
    // req.set_path_with_query(Some("/")) is intentionally omitted

    let _ = handle(req, None);
}

If your environment is affected, the final call may trap, panic, or terminate the runtime instead of returning an error such as an invalid-argument failure.

Understanding the Root Cause

This bug comes from a mismatch between the WASI HTTP API contract and the runtime implementation. An OutgoingRequest is not valid unless its required components are present in a coherent state. In particular, request metadata such as scheme, authority, and path/query must be validated before the host attempts to transform that data into an internal HTTP request.

When path_with_query is missing, the runtime should detect that the request is incomplete and return a structured error. Instead, the implementation reaches a code path that assumes required fields already exist. That assumption causes one of several failure modes:

• A direct panic from an unchecked unwrap or invariant assertion.
• A trap caused by invalid lowering/lifting of component-model values.
• An internal host error that is not mapped back into the expected WASI HTTP result type.

Technically, the root problem is insufficient input validation at the host boundary. The host function must treat all guest-provided values as untrusted, even when they come from generated bindings. If validation occurs too late, internal request-building code may operate on partially initialized state and crash before an error value can be returned.

The correct behavior is:

1. Inspect all required request fields before dispatch.
2. Reject missing or malformed values deterministically.
3. Return a normal error result through the WASI HTTP interface.
4. Never let malformed guest input crash wasmtime.

Step-by-Step Solution

The fix has two parts: runtime-side hardening and caller-side defensive construction.

1. Reproduce the issue with a focused test

Start by codifying the failure so the regression is easy to verify.

#[test]
fn outgoing_handler_rejects_missing_path_with_query() {
    use wasi::http::outgoing_handler::handle;
    use wasi::http::types::{Fields, OutgoingRequest, Scheme};

    let headers = Fields::new();
    let req = OutgoingRequest::new(headers);

    req.set_scheme(Some(&Scheme::Https)).unwrap();
    req.set_authority(Some("example.com")).unwrap();
    // Missing path_with_query

    let result = handle(req, None);

    // Expected: error result, not crash
    assert!(result.is_err() || matches!(result, Ok(_)));
}

If this test aborts the process or crashes the runtime, you have confirmed the host-side validation gap.

2. Validate required fields before internal request conversion

If you are patching wasmtime or a host implementation, add explicit validation at the boundary where OutgoingRequest is converted into the runtime’s internal HTTP representation.

fn validate_outgoing_request(req: &OutgoingRequestState) -> Result<(), HttpRequestError> {
    if req.path_with_query.is_none() {
        return Err(HttpRequestError::InvalidArgument(
            "path_with_query is required".to_string(),
        ));
    }

    if req.scheme.is_none() {
        return Err(HttpRequestError::InvalidArgument(
            "scheme is required".to_string(),
        ));
    }

    if req.authority.is_none() {
        return Err(HttpRequestError::InvalidArgument(
            "authority is required".to_string(),
        ));
    }

    Ok(())
}

Then call that validator before any unwraps, URI parsing, or request dispatch logic:

pub fn handle(req: OutgoingRequest, options: Option<RequestOptions>) -> Result<ResponseOutparam, ErrorCode> {
    let state = extract_request_state(&req)?;

    validate_outgoing_request(&state)
        .map_err(map_request_error_to_error_code)?;

    let internal_req = build_internal_request(state)
        .map_err(map_request_error_to_error_code)?;

    dispatch_request(internal_req, options)
}

This is the key correction: validate first, convert second, dispatch last.

3. Replace panicking assumptions with error propagation

Search for code patterns like these in the implementation:

let path = req.path_with_query.as_ref().unwrap();
let authority = req.authority.expect("authority must be set");

Replace them with recoverable error handling:

let path = req
    .path_with_query
    .as_ref()
    .ok_or_else(|| HttpRequestError::InvalidArgument("missing path_with_query".into()))?;

let authority = req
    .authority
    .as_ref()
    .ok_or_else(|| HttpRequestError::InvalidArgument("missing authority".into()))?;

This ensures malformed input never escapes into a panic-producing branch.

4. Map validation failures to the public WASI HTTP error type

An internal validation error is only useful if it becomes a proper public API error.

fn map_request_error_to_error_code(err: HttpRequestError) -> ErrorCode {
    match err {
        HttpRequestError::InvalidArgument(_) => ErrorCode::HttpRequestUriInvalid,
        HttpRequestError::InvalidHeader(_) => ErrorCode::HttpProtocolError,
        HttpRequestError::Internal(_) => ErrorCode::InternalError,
    }
}

The exact variant names depend on the version of the API and bindings you are using, but the design goal stays the same: return a structured error instead of crashing the runtime.

5. Add regression tests for malformed requests

Once fixed, lock the behavior in with targeted tests.

#[test]
fn missing_path_returns_error_not_panic() {
    let result = make_request_without_path();
    assert!(result.is_err());
}

#[test]
fn missing_authority_returns_error_not_panic() {
    let result = make_request_without_authority();
    assert!(result.is_err());
}

#[test]
fn missing_scheme_returns_error_not_panic() {
    let result = make_request_without_scheme();
    assert!(result.is_err());
}

Regression coverage matters because these bugs often reappear when request-construction logic is refactored.

6. Apply a safe caller-side workaround

If you cannot patch the runtime immediately, construct OutgoingRequest defensively and verify all required fields before calling handle.

use wasi::http::outgoing_handler::handle;
use wasi::http::types::{Fields, OutgoingRequest, Scheme};

fn safe_handle() {
    let headers = Fields::new();
    let req = OutgoingRequest::new(headers);

    req.set_scheme(Some(&Scheme::Https)).unwrap();
    req.set_authority(Some("example.com")).unwrap();
    req.set_path_with_query(Some("/")).unwrap();

    let result = handle(req, None);

    match result {
        Ok(response) => {
            let _ = response;
        }
        Err(err) => {
            eprintln!("request failed: {:?}", err);
        }
    }
}

This does not fix the underlying runtime bug, but it prevents the known crash scenario in application code.

Common Edge Cases

• Missing scheme: A request with authority and path but no scheme may hit the same invalid-state path if the host assumes a complete URI.
• Missing authority: Especially common when callers expect relative-path requests to work. Some implementations require a full authority for outbound HTTP.
• Malformed path/query: Values that do not begin with /, contain invalid characters, or include broken percent-encoding should return an error, not panic.
• Invalid headers: Header names with illegal bytes or values that violate HTTP constraints can expose the same class of host validation bugs.
• Incorrect field ordering assumptions: If the implementation assumes setters are called in a specific order, partially built requests may trigger unexpected failures.
• Version mismatch: Different WASI HTTP or wasmtime versions may expose the error differently, making it look like separate bugs when the underlying cause is the same missing validation layer.

When debugging similar failures, treat every guest-originated request field as potentially absent, malformed, or inconsistent.

FAQ

1. Why does handle crash instead of returning an error?

Because the implementation is likely using unchecked assumptions about required request fields. If internal code unwraps path_with_query before validating it, the runtime can panic or trap before it has a chance to return a WASI HTTP error.

2. Is this an application bug or a wasmtime bug?

It is both a malformed input case and a runtime robustness bug. Application code should build valid requests, but wasmtime still must not crash on invalid guest input. The correct host behavior is to return a recoverable error.

3. What is the safest immediate workaround?

Always set scheme, authority, and path_with_query before calling handle, and add your own preflight validation in guest code. If you maintain the host, patch the conversion layer so invalid requests are rejected with structured error codes.

For long-term stability, the best fix is to enforce boundary validation inside the host implementation and back it with regression tests covering missing and malformed request fields.