Expect to have a document while transforming linked field

Error message

Expect to have a document while transforming linked field

What it means

While validating @required metadata for a field, validate_semantic_non_null_for_field needs the current document name to check whether the disallow_required_action_throw_on_semantically_nullable_fields feature flag is enabled for it. If self.current_document_name is None the expect panics, meaning the validation ran outside of a document context.

Source

Thrown at compiler/crates/relay-transforms/src/required_directive.rs:287

                    .annotate(
                        "so that it can match its parent",
                        required_child.required.action_location,
                    ),
                );
            }
        }
    }
    fn validate_semantic_non_null_for_field(
        &mut self,
        field: &schema::definitions::Field,
        metadata: RequiredMetadata,
    ) {
        let enforce_no_throw_on_nullable = self
            .feature_flags
            .disallow_required_action_throw_on_semantically_nullable_fields
            .is_enabled_for(
                self.current_document_name
                    .expect("Expect to have a document while transforming linked field"),
            );

        if field.semantic_type().is_non_null() {
            if metadata.action == RequiredAction::DangerouslyThrowOnSemanticallyNullableField {
                self.errors.push(Diagnostic::error_with_data(
                    RequiredDirectiveValidationMessageWithData::DangerousThrowActionOnNonNullableFieldWithFix,
                    metadata.action_location,
                ));
            }
        } else if metadata.action == RequiredAction::Throw && enforce_no_throw_on_nullable {
            self.errors.push(Diagnostic::error_with_data(
                    RequiredDirectiveValidationMessageWithData::ThrowActionOnSemanticNullableFieldWithFix,
                    metadata.action_location,
                ));
        }
    }

    fn assert_compatible_required_children<T: RequireableField>(

View on GitHub (pinned to 668b1b85e0)

Solutions

Ensure the transform sets current_document_name before visiting (in the entry point for each operation/fragment).
Invoke @required validation through the standard Relay transform pipeline rather than calling get_required_metadata directly.
Make current_document_name an explicit parameter so the compiler enforces it (local fork fix).
File a relay compiler bug with the document that triggers it if the standard pipeline panics.

Example fix

// before
let enforce = self.feature_flags...is_enabled_for(
    self.current_document_name
        .expect("Expect to have a document while transforming linked field"),
);
// after
let Some(doc) = self.current_document_name else { return Ok(()) };
let enforce = self.feature_flags...is_enabled_for(doc);

Defensive patterns

Strategy: validation

Validate before calling

assert!(self.current_document_name.is_some(), "required_directive validation invoked outside a document context");

Type guard

fn in_document(state: &TransformState) -> bool { state.current_document_name.is_some() }

Try / catch

let Some(doc) = self.current_document_name else { return Ok(()); };

Prevention

Set current_document_name in the visitor entry point for every document.
Do not reuse the @required visitor outside the transform pipeline.
Make document context an explicit function parameter.

When it happens

Trigger: get_required_metadata (linked-field handling in required_directive.rs) invoked with no current document set — typically when the transform/visitor processes an IR node without the document-scoped state being initialized, or when @required validation is invoked on a sub-selection outside a named operation/fragment.

Common situations: Custom tooling that reuses the required_directive visitor outside the normal transform entry point; language-server or per-node compilation paths that skip setting current_document_name; @required on a fragment compiled without an enclosing document context.

Related errors

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