{"record":{"id":"3177c04f17b1e0f0","repo":"hasura/graphql-engine","slug":"the-global-id-encoded-value-couldn-t-be-decoded","errorCode":null,"errorMessage":"The global ID {encoded_value:} couldn't be decoded due to {decoding_error:}","messagePattern":"The global ID (.+?) couldn't be decoded due to (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/crates/graphql/ir/src/error.rs","lineNumber":40,"sourceCode":"                InternalEngineError::PlanInternalEngineError(engine_error),\n            )),\n            plan::InternalError::Developer(developer_error) => {\n                Error::Internal(InternalError::Developer(\n                    InternalDeveloperError::PlanInternalDeveloperError(developer_error),\n                ))\n            }\n        }\n    }\n}\n\n#[allow(clippy::duplicated_attributes)] // suppress spurious warnings from Clippy\n#[derive(Error, Debug, Transitive)]\n#[transitive(from(json::Error, InternalError))]\n#[transitive(from(gql::normalized_ast::Error, InternalError))]\n#[transitive(from(InternalEngineError, InternalError))]\n#[transitive(from(InternalDeveloperError, InternalError))]\npub enum Error {\n    #[error(\"The global ID {encoded_value:} couldn't be decoded due to {decoding_error:}\")]\n    FailureDecodingGlobalId {\n        encoded_value: String,\n        decoding_error: String,\n    },\n\n    #[error(\"Unexpected value: expecting {expected_kind:}, but found: {found:}\")]\n    UnexpectedValue {\n        expected_kind: &'static str,\n        found: json::Value,\n    },\n\n    #[error(\"'{name:}' is not a valid GraphQL name.\")]\n    TypeFieldInvalidGraphQlName { name: String },\n\n    #[error(\"'{alias:} is not a valid alias\")]\n    InvalidAlias { alias: String },\n\n    #[error(\"{value} is not a valid limit value\")]","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/graphql/ir/src/error.rs#L22-L58","documentation":"Thrown by the GraphQL IR layer when a relay-style global ID (the base64-encoded 'typename:id' composite) fails to decode. The error carries the raw encoded value and the underlying decoding error message. This typically happens when a value passed as a global ID is malformed, not base64, or doesn't split into the expected node type and ID components.","triggerScenarios":"Passing a non-global-ID string (e.g. a raw database ID or arbitrary text) to an argument that expects a node ID; passing a global ID encoded with a different scheme or whose base64 payload doesn't contain the expected separator; corrupted ID from client-side manipulation.","commonSituations":"Clients fabricating IDs or reusing IDs from another environment/encoder; migrating ID formats while stale clients still send old IDs; copy-paste truncation of base64 values.","solutions":["Regenerate the ID by fetching it from the server (query the node's id field) rather than constructing it client-side","Verify the ID is the exact base64 string returned by a previous response and hasn't been URL-decoded/trimmed","If you control the encoder, confirm the 'typename:id' format and base64 variant match the server's decoder"],"exampleFix":"# before\nquery {{ user(id: \"12345\") {{ id }} }}\n\n# after (use the global ID returned by the server)\nquery {{ user(id: \"VXNlcjoxMjM0NQ==\") {{ id }} }}","handlingStrategy":"validation","validationCode":"function isGlobalId(v: string): boolean {{\n  try {{\n    const decoded = atob(v);\n    return /^[^:]+:.+$/.test(decoded);\n  }} catch {{ return false; }}\n}}\nif (!isGlobalId(idArg)) throw new TypeError('Expected a server-issued global ID');","typeGuard":"function isGlobalId(v: string): v is string {{\n  try {{ return /^[^:]+:.+$/.test(atob(v)); }} catch {{ return false; }}\n}}","tryCatchPattern":"try {{\n  const node = await client.request({{ query: NODE_QUERY, variables: {{ id }} }}); \n}} catch (e: any) {{\n  if (/global ID.*couldn't be decoded/.test(e.message)) {{ /* re-fetch valid ID or return null */ }}\n  throw e;\n}}","preventionTips":["Always round-trip IDs from server responses instead of constructing them","Never store raw DB IDs where the API expects global IDs","Guard shared IDs with a decode-and-check helper before sending"],"tags":["graphql","global-id","relay","base64","decoding","rust"],"backgroundTag":"invalid-global-id","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}