facebook/relay · error

Unexpected RelayResolverMetadata on inline fragment while ge

Error message

Unexpected RelayResolverMetadata on inline fragment while generating Reader AST

What it means

RelayResolverMetadata attached to an inline fragment is only meaningful when generating Normalization ASTs. During Reader AST generation, build_selections_from_selection panics if it finds resolver metadata on an inline fragment, since the reader pipeline has no representation for it.

Source

Thrown at compiler/crates/relay-codegen/src/build_ast.rs:894

                    InlineDirectiveMetadata::find(&inline_fragment.directives)
                {
                    // If inline fragment has @__inline directive (created by inline_data_fragment transform)
                    // we will return selection wrapped with InlineDataFragmentSpread
                    vec![self.build_inline_data_fragment_spread(
                        context,
                        inline_fragment,
                        inline_data_directive,
                    )]
                } else if let Some(module_metadata) =
                    ModuleMetadata::find(&inline_fragment.directives)
                {
                    self.build_module_import_selections(module_metadata, inline_fragment)
                } else if let Some(resolver_metadata) =
                    RelayResolverMetadata::find(&inline_fragment.directives)
                {
                    match self.variant {
                        CodegenVariant::Reader => {
                            panic!(
                                "Unexpected RelayResolverMetadata on inline fragment while generating Reader AST"
                            )
                        }
                        CodegenVariant::Normalization => {
                            let fragment_primitive =
                                self.build_inline_fragment(context, inline_fragment);

                            vec![self.build_normalization_relay_resolver(
                                context,
                                resolver_metadata,
                                Some(fragment_primitive),
                            )]
                        }
                    }
                } else {
                    vec![self.build_inline_fragment(context, inline_fragment)]
                }
            }

View on GitHub (pinned to 668b1b85e0)

Solutions

1. Run the document through the full relay compiler pipeline (which generates both Reader and Normalization variants) instead of invoking reader-only codegen on resolver fragments.
2. Remove or fix the stray @relay_resolver / resolver metadata on the inline fragment if it isn't an actual resolver.
3. Check custom codegen entry points to pass CodegenVariant::Normalization for fragments with resolver metadata.
4. Upgrade the compiler so reader handling of resolver inline fragments matches your document's shape.

Example fix

// before (custom codegen)
build_selections(ctx, selections, CodegenVariant::Reader); // fragment has resolver metadata
// after
build_selections(ctx, selections, CodegenVariant::Normalization); // or use full relay compile

fn inline_fragment_is_reader_safe(frag: &InlineFragment) -> bool {
    RelayResolverMetadata::find(&frag.directives).is_none()
}

fn has_resolver_metadata(directives: &[Directive]) -> bool {
    RelayResolverMetadata::find(directives).is_some()
}

let result = std::panic::catch_unwind(|| build_selections_reader(...));
if result.is_err() { report("resolver metadata found on inline fragment in reader codegen"); }

When it happens

Trigger: A client-edge/resolver inline fragment (e.g. from @refetchable or a @relay_resolver marker) is compiled while CodegenVariant::Reader is active and the inline fragment carries RelayResolverMetadata directives.

Common situations: Compiling a document with resolver-bearing inline fragments through a code path meant only for reader generation; using a custom build script that invokes build_selections with the wrong variant; version mismatch where a newer schema/fragment shape is fed to an older reader codegen.

Related errors

• Unexpected parent type for resolver.
• The {} argument in exec_time_resolvers directive should be t
• Expected at most one handle directive, got `{handle_field_di
• Unexpected RelayResolverMetadata on fragment spread while ge
• Unexpected custom directives: {:#?}

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