{"record":{"id":"c7415997986dba13","repo":"TanStack/query","slug":"the-usage-in-file-filepath-at-line-start-c74159","errorCode":null,"errorMessage":"The usage in file \"${filePath}\" at line ${start}:${end} could not be transformed into the new syntax. Please do this manually.","messagePattern":"The usage in file \"(.+?)\" at line (.+?):(.+?) could not be transformed into the new syntax\\. Please do this manually\\.","errorType":"exception","errorClass":"UnknownUsageError","httpStatus":null,"severity":"warning","filePath":"packages/query-codemods/src/v5/remove-overloads/utils/index.cjs","lineNumber":47,"sourceCode":"    const scope = path.scope.declares(argumentName)\n      ? path.scope\n      : path.scope.lookup(argumentName)\n\n    /**\n     * The declaration couldn't be found for some reason, time to move on. We warn the user it needs to be rewritten\n     * by themselves.\n     */\n    if (!scope) {\n      return undefined\n    }\n\n    const binding = scope.bindings[argumentName]\n      .filter((item) => utils.isIdentifier(item.value))\n      .map((item) => item.parentPath.value)\n      .at(0)\n\n    if (!binding) {\n      throw new UnknownUsageError(path.node, filePath)\n    }\n\n    return binding\n  }\n\n  /**\n   * @param {import('jscodeshift').VariableDeclarator} binding\n   * @returns {import('jscodeshift').Node|undefined}\n   */\n  const getInitializerByDeclarator = (binding) => {\n    const isVariableDeclaration = jscodeshift.match(binding, {\n      type: jscodeshift.VariableDeclarator.name,\n    })\n\n    if (!isVariableDeclaration) {\n      return undefined\n    }\n","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/TanStack/query/blob/159982c80b844487054155c38ffc760fe4208daf/packages/query-codemods/src/v5/remove-overloads/utils/index.cjs#L29-L65","documentation":"Thrown by the v5 `remove-overloads` codemod (UnknownUsageError) when it cannot statically resolve the binding for an identifier passed as a query/mutation key during the v4 -> v5 transform. The codemod found the call site but could not infer what value the identifier refers to (e.g. it is imported, computed, or has an unhandled shape), so it aborts that call and asks the developer to migrate it by hand. It is a build/migration-time error from `@tanstack/query-codemods`, not a runtime error of TanStack Query.","triggerScenarios":"Running `npx @tanstack/query-codemods@latest` (or the v5 `remove-overloads` transform specifically) against a source file where a Query/Mutation method's first argument is an identifier whose binding is not an `Identifier`-typed AST node the codemod recognises — e.g. `useQuery(myKey, fn)` where `myKey` is imported from another module, generated by a function call, spread from another object, or declared with a non-standard pattern. Triggered when `scope.bindings[argumentName]` exists but none of the items pass `utils.isIdentifier(item.value)`, so `binding` is `undefined`.","commonSituations":"Migrating a large codebase to TanStack Query v5 where query keys are exported from a shared `queryKeys.ts` factory module, defined via a key builder function (`todoKeys.list()`), imported across files, or constructed with `as const` inside another variable. Also occurs with monorepo setups where the codemod runs per-file and cannot see cross-package bindings.","solutions":["Open the file and line reported in the error message and manually convert the call to the v5 object syntax, e.g. `useQuery({ queryKey: myKey, queryFn })`.","If the key is imported from another module, inline it or restructure so the codemod can see a local array declaration, then re-run the transform.","Re-run the codemod with `--dry` to preview remaining call sites and confirm how many still fail before committing.","Upgrade `@tanstack/query-codemods` to the latest version — later releases handle more binding shapes (TSAsExpression, ArrayExpression, etc.)."],"exampleFix":"// before (v4) - myKey is imported, codemod cannot resolve it\nimport { myKey } from './keys'\nuseQuery(myKey, fetchTodos)\n\n// after (v5) - wrap in object manually\nimport { myKey } from './keys'\nuseQuery({ queryKey: myKey, queryFn: fetchTodos })","handlingStrategy":"try-catch","validationCode":"// Before running the codemod, grep for patterns the codemod cannot resolve\nconst fs = require('fs')\nconst src = fs.readFileSync(filePath, 'utf8')\n// Heuristic: query/mutation calls whose first arg is a bare identifier that is imported\nconst suspicious = [...src.matchAll(/\\b(?:useQuery|useMutation|useInfiniteQuery)\\s*\\(\\s*([A-Za-z_$][\\w$]*)\\s*,/g)]\n  .map(m => m[1])\n  .filter(name => /^import\\b[^;]*\\b${name}\\b/m.test(src))\nconsole.log(suspicious.length ? `Review manually: ${suspicious.join(', ')}` : 'OK')","typeGuard":"// The codemod's own predicate - mirror it to predict failures\nconst isResolvableBinding = (bindingItems, utils) =>\n  bindingItems.some((item) => utils.isIdentifier(item.value))","tryCatchPattern":"// Wrap the codemod transform so one unresolvable call does not abort the file\ntry {\n  await runCodemod(file)\n} catch (e) {\n  if (e.name === 'UnknownUsageError') {\n    console.warn(`Manual migration needed: ${e.message}`)\n    pendingManual.add(file)\n  } else {\n    throw e\n  }\n}","preventionTips":["Keep query keys as local array literals (`const todosKey = ['todos']`) so the codemod can see the ArrayExpression binding.","Run the codemod with --dry first to enumerate failures before mutating files.","Upgrade @tanstack/query-codemods to the latest release before migrating.","For shared key factories, inline or localise the keys during migration, then refactor back afterwards."],"tags":["codemod","migration","v5","ast","build-time"],"backgroundTag":null,"analyzedSha":"159982c80b844487054155c38ffc760fe4208daf","analyzedAt":"2026-08-12T16:21:52.822Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}