facebook/relay · error

Expected handler_arg to have been previously validated or a

Error message

Expected handler_arg to have been previously validated or a default to have been provided.

What it means

Unwrap guard in extract_values_from_handle_field_directive_helper: handler_arg must be a string literal because either the caller supplied a default handler or validate_connections validated it. Firing means neither a validated literal handler nor a usable default was present, i.e. the directive reached transform without validation and without a default.

Source

Thrown at compiler/crates/relay-transforms/src/handle_fields/handle_field_util.rs:226

    let HandleFieldDirectiveArgs {
        handler_arg,
        filters_arg,
        key_arg,
        dynamic_key_arg,
        handle_args_arg,
    } = extract_handle_field_directive_args_helper(handle_field_directive, hanlder_arg_name);

    // We expect these values to be available since they should've been
    // validated first as part of validate_connections validation step.
    let key = match key_arg {
        Some((_, value)) => value
            .get_string_literal()
            .expect("Expected key_arg to have been previously validated."),
        None => "".intern(),
    };
    let handle= match handler_arg {
         Some((_, value)) => value.get_string_literal().expect("Expected handler_arg to have been previously validated."),
         None => default_handler.expect("Expected handler_arg to have been previously validated or a default to have been provided."),
     };
    let filters = match filters_arg {
        Some((_, value)) => match value {
            ConstantValue::List(list_val) => Some(
                list_val
                    .iter()
                    .map(|val| {
                        val.get_string_literal()
                            .expect("Expected filters_arg to have been previously validated.")
                    })
                    .collect::<Vec<_>>(),
            ),
            ConstantValue::Null() => None,
            _ => unreachable!("Expected filters_arg to have been previously validated.",),
        },
        None => default_filters,
    };
    let dynamic_key = match dynamic_key_arg {

View on GitHub (pinned to 668b1b85e0)

Solutions

1. Pass default_handler when building handle field directives without an explicit handler argument
2. Guarantee validate_connections runs first so handler_arg is a validated string literal
3. Replace the expect with a diagnostic error surfacing the offending directive location

When it happens

Trigger: Thrown at compiler/crates/relay-transforms/src/handle_fields/handle_field_util.rs:226 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of facebook/relay@668b1b85e0 (2026-09-02). Data as JSON: /api/errors/61c4b28b92c46add. Report an issue: GitHub.