facebook/relay · error

{diagnostics}

Error message

{diagnostics}

What it means

format_document parses a GraphQL executable document string before pretty-printing it. If parse_executable produces GraphQL diagnostics, they are joined with newlines into an anyhow error. It means the input string is not a syntactically valid GraphQL executable document, so formatting cannot proceed.

Source

Thrown at compiler/crates/graphql-ir-diff/src/lib.rs:763

            }
            _ => (),
        }
    }
}

pub fn collect_normalized_tree(program: &Program) -> Rc<NormalizedTree> {
    let mut collector = NormalizedTreeCollector::new(&program.schema);
    collector.visit_program(program);
    assert!(
        collector.stack.len() == 1,
        "stack must be size 1 post visit"
    );
    collector.stack.last().unwrap().clone()
}

pub fn format_document(document: &str) -> Result<String> {
    let ast = parse_executable(document, SourceLocationKey::generated())
        .map_err(|diagnostics| anyhow::anyhow!(diagnostics.iter().join("\n")))?;

    let formatted: String = ast
        .definitions
        .iter()
        .map(print_executable_definition_ast)
        .collect::<Vec<_>>()
        .join("\n\n");

    Ok(formatted)
}

pub fn parse(schema: Arc<SDLSchema>, document: &str) -> Result<Program> {
    let ast = parse_executable(document, SourceLocationKey::generated())
        .map_err(|diagnostics| anyhow::anyhow!(diagnostics.iter().join("\n")))?;
    let ir = build_ir_with_extra_features(
        &schema,
        &ast.definitions,
        &BuilderOptions {

View on GitHub (pinned to 668b1b85e0)

Solutions

1. Read the joined diagnostics in the error message; they pinpoint file-less generated-source locations of each syntax error.
2. Validate/fix the GraphQL syntax of the document before formatting (e.g. run it through a linter or editor GraphQL plugin).
3. Ensure the input is a document of executable definitions (query/mutation/subscription/fragment), not a schema/type-system document.
4. Check for stray interpolation artifacts (unescaped braces, placeholder text) in generated documents.

Example fix

// before
format_document("query { user { name }")  // unbalanced brace
// after
format_document("query { user { name } }")

// Best-effort pre-check: parse before formatting
match parse_executable(document, SourceLocationKey::generated()) {
    Ok(_) => format_document(document)?,
    Err(diags) => eprintln!("invalid document: {}", diags.iter().join("\n")),
}

match format_document(doc) {
    Ok(formatted) => formatted,
    Err(e) => { log::error!("format_document failed: {e}"); fallback_raw(doc) }
}

When it happens

Trigger: Calling format_document(document) with text containing GraphQL syntax errors — unbalanced braces, invalid characters, misplaced tokens, non-executable garbage text.

Common situations: Diff tooling feeding test snapshots or fixture files that contain intentional invalid GraphQL; files saved with wrong encoding; documents interpolated with broken template strings in build scripts.

Related errors

• Parse error: {:?}
• Failed to build schema: {}
• BabelPluginRelay: Expected exactly one definition per graphq
• BabelPluginRelay: Expected a fragment, mutation, query, or s
• GraphQL operations and fragments must contain names

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