{"record":{"id":"7009ee5a97fd29c7","repo":"TanStack/query","slug":"in-file-filepath-at-line-node-loc-start-line","errorCode":null,"errorMessage":"In file ${filePath} at line ${node.loc.start.line} the type of identifier \\`${node.name}\\` couldn't be recognized, so the codemod couldn't be applied. Please migrate manually.","messagePattern":"In file (.+?) at line (.+?) the type of identifier \\\\`(.+?)\\\\` couldn't be recognized, so the codemod couldn't be applied\\. Please migrate manually\\.","errorType":"exception","errorClass":"UnprocessableKeyError","httpStatus":null,"severity":"warning","filePath":"packages/query-codemods/src/v4/utils/replacers/key-replacer.cjs","lineNumber":53,"sourceCode":"      return jscodeshift.arrayExpression([\n        jscodeshift.stringLiteral(node.value),\n      ])\n    }\n\n    // When the node is a template literal we convert it into an array of template literals.\n    if (isTemplateLiteral(node)) {\n      return jscodeshift.arrayExpression([\n        jscodeshift.templateLiteral(node.quasis, node.expressions),\n      ])\n    }\n\n    if (jscodeshift.match(node, { type: jscodeshift.Identifier.name })) {\n      // When the node is an identifier at first, we try to find its declaration, because we will try\n      // to guess its type.\n      const variableDeclaration = findVariableDeclaration(node)\n\n      if (!variableDeclaration) {\n        throw new UnprocessableKeyError(\n          `In file ${filePath} at line ${node.loc.start.line} the type of identifier \\`${node.name}\\` couldn't be recognized, so the codemod couldn't be applied. Please migrate manually.`,\n        )\n      }\n\n      const initializer = variableDeclaration.value.init\n\n      // When it's a string, we just wrap it into an array expression.\n      if (isStringLiteral(initializer) || isTemplateLiteral(initializer)) {\n        return jscodeshift.arrayExpression([node])\n      }\n    }\n\n    throw new UnprocessableKeyError(\n      `In file ${filePath} at line ${node.loc.start.line} the type of the \\`${keyName}\\` couldn't be recognized, so the codemod couldn't be applied. Please migrate manually.`,\n    )\n  }\n\n  const createKeyProperty = (node) =>","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/TanStack/query/blob/159982c80b844487054155c38ffc760fe4208daf/packages/query-codemods/src/v4/utils/replacers/key-replacer.cjs#L35-L71","documentation":"`UnprocessableKeyError` from the v4 codemod's `key-replacer.cjs`. When the AST node for a query key is an `Identifier`, the codemod tries to find its `const` declaration (`findVariableDeclaration`) to guess the type. If no declaration is found (e.g. a parameter, an import, or a destructured binding), it cannot safely transform and throws with the file path and line number for manual migration.","triggerScenarios":"Running the v4 codemod on code where the query key is an identifier whose declaration is not a simple `const x = ...` in scope: function parameters, imported bindings, destructured variables, properties (`obj.key`), loop variables, or identifiers declared with `let`/`var` in a different block.","commonSituations":"Migrating a large v3->v4 codebase with non-trivial key indirection; codemod applied to partial files; keys computed from props/parameters in shared hooks; older codebases with `var` declarations.","solutions":["Open the cited file:line and convert the query key to a literal array or template literal so the codemod can handle it, then re-run.","Manually wrap the identifier: `useQuery([myKey], ...)` -> `useQuery({ queryKey: [myKey], queryFn: ... })`.","Hoist the identifier into a `const` array literal near the call site so the codemod finds its declaration.","Re-run the codemod on the fixed file and verify other call sites still transform."],"exampleFix":"// before\nuseQuery(myKey, fetchFn)\n// after (manual)\nuseQuery({ queryKey: [myKey], queryFn: fetchFn })","handlingStrategy":"try-catch","validationCode":"// Codemod-side: pre-scan for identifiers without findable declarations.\nfunction hasSimpleDeclaration(scope: any, name: string): boolean {\n  const node = scope.lookup(name)\n  return !!node && node.value?.init\n}","typeGuard":null,"tryCatchPattern":"// Drive the codemod and collect failures for manual review.\nconst report = []\nfor (const file of files) {\n  try { runCodemod(file) }\n  catch (e) { if (e.name === 'UnprocessableKeyError') report.push({ file, message: e.message }) }\n}","preventionTips":["Simplify key identifiers to local `const` array literals before running the codemod.","Avoid imported/parameter key bindings at query call sites during migration.","Run the codemod per-file and collect the cited file:line for manual follow-up.","Re-run after manual fixes to confirm transformation."],"tags":["codemod","v4-migration","ast","manual-migration","key-replacer"],"backgroundTag":null,"analyzedSha":"159982c80b844487054155c38ffc760fe4208daf","analyzedAt":"2026-08-12T16:21:52.822Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}