{"record":{"id":"f8834b5f76718b55","repo":"hasura/graphql-engine","slug":"fragment-not-defined-in-the-document-0","errorCode":null,"errorMessage":"fragment not defined in the document: {0}","messagePattern":"fragment not defined in the document: (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/crates/graphql/lang-graphql/src/validation/error.rs","lineNumber":14,"sourceCode":"use thiserror::Error;\n\nuse crate::ast::{common as ast, spanning};\n\npub type Result<T> = core::result::Result<T, Error>;\n\n#[derive(Error, Debug, Clone)]\npub enum Error {\n    #[error(\"fragment cycle detected through: {0:?}\")]\n    CycleDetected(Vec<ast::Name>),\n    // TODO, this error isn't thrown yet\n    #[error(\"unused fragment: {0}\")]\n    FragmentNotUsed(ast::Name),\n    #[error(\"fragment not defined in the document: {0}\")]\n    UnknownFragment(ast::Name),\n    #[error(\"{} is defined on a non-composite type: {type_name}\", match fragment_name { None => \"inline fragment\".to_owned(), Some(fragment_name) => format!(\"fragment {fragment_name}\")})]\n    FragmentOnNonCompositeType {\n        fragment_name: Option<ast::Name>,\n        type_name: ast::TypeName,\n    },\n    #[error(\"fragment of type {fragment_type} cannot be spread on type {selection_type}\")]\n    FragmentCannotBeSpread {\n        selection_type: ast::TypeName,\n        fragment_type: ast::TypeName,\n    },\n    // TODO, this error isn't thrown yet\n    #[error(\n        \"a selection set is specified on field '{field_name}' of non-composite type: {type_name}\"\n    )]\n    SelectionOnNonCompositeType {\n        field_name: ast::Name,\n        type_name: ast::TypeName,","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/graphql/lang-graphql/src/validation/error.rs#L1-L32","documentation":"Thrown when a query document spreads a named fragment (e.g. `...MyFragment`) that is not defined anywhere in the same executable document. The validator looks up fragment definitions when collecting fields (validation/collect.rs collect_fields_internal) and in check_fragment_cycles (validation.rs:127); a missing definition yields UnknownFragment carrying the fragment name. GraphQL requires every fragment spread to resolve within the same document.","triggerScenarios":"Executing a query string that contains `...SomeFragment` without including the corresponding `fragment SomeFragment on X { ... }` definition in the same document; concatenating query strings but dropping the fragment portion; typos in the fragment name after `...`.","commonSituations":"Client code sends only the query operation while fragment definitions live in a different string/file that was never appended; codegen splits queries and fragments and only the operation is transmitted; refactoring renames a fragment but not all its spreads.","solutions":["Ensure every `...Name` spread has a matching `fragment Name on Type { ... }` definition in the same document sent to the server","Check for typos/case mismatches between the spread name and the fragment definition name","If building the document programmatically, concatenate all fragment definitions from your query source before calling validation/execution"],"exampleFix":"// before\nquery { user { ...UserFields } }\n// after\nquery { user { ...UserFields } }\nfragment UserFields on User { id name }","handlingStrategy":"validation","validationCode":"let defined: HashSet<&str> = doc.definitions().iter().filter_map(|d| match d { Definition::Fragment(f) => Some(f.name.as_str()), _ => None }).collect();\nfor spread in collect_spreads(doc) { assert!(defined.contains(spread), \"missing fragment {spread}\"); }","typeGuard":"fn has_fragment_def(doc: &Document<()>, name: &str) -> bool { doc.definitions().iter().any(|d| matches!(d, Definition::Fragment(f) if f.name.as_str() == name)) }","tryCatchPattern":"match validator.validate(&schema, &doc) { Err(e @ Error::UnknownFragment(_)) => report_user_error(e), r => r }","preventionTips":["Always ship fragment definitions in the same document as their spreads","Use a query builder that tracks fragments automatically","Add a preflight check that every `...Name` spread has a definition"],"tags":["graphql","fragment","validation","query-document"],"backgroundTag":"graphql-fragment-not-defined","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}