{"record":{"id":"5c1ae7b8f061d77f","repo":"TanStack/query","slug":"the-usage-in-file-filepath-at-line-start-5c1ae7","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/transformers/filter-aware-usage-transformer.cjs","lineNumber":156,"sourceCode":"       * @type {import('jscodeshift').Property|undefined}\n       */\n      const keyProperty = v5Utils.transformArgumentToKey(\n        path,\n        node.arguments[0],\n        config.keyName,\n        filePath,\n      )\n\n      /**\n       * The first parameter couldn't be transformed into an object property, so it's time to throw an exception,\n       * it will notify the consumers that they need to rewrite this usage manually.\n       */\n      if (!keyProperty) {\n        const secondArgument =\n          node.arguments.length > 1 ? node.arguments[1] : null\n\n        if (!secondArgument) {\n          throw new UnknownUsageError(node, filePath)\n        }\n\n        if (utils.isFunctionDefinition(secondArgument)) {\n          const originalArguments = node.arguments\n          const firstArgument = jscodeshift.objectExpression([\n            jscodeshift.property(\n              'init',\n              jscodeshift.identifier(config.keyName),\n              originalArguments[0],\n            ),\n            jscodeshift.property(\n              'init',\n              jscodeshift.identifier(config.fnName),\n              secondArgument,\n            ),\n          ])\n\n          return jscodeshift.callExpression(node.original.callee, [","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/TanStack/query/blob/159982c80b844487054155c38ffc760fe4208daf/packages/query-codemods/src/v5/remove-overloads/transformers/filter-aware-usage-transformer.cjs#L138-L174","documentation":"`UnknownUsageError` from the v5 `remove-overloads` codemod's `filter-aware-usage-transformer`. The transformer tries to convert the first positional argument into a `queryKey`/`mutationKey` property; if that fails (`keyProperty` is null) AND there is no second argument that is a function (which it could repurpose as `queryFn`), the usage is too ambiguous to transform safely.","triggerScenarios":"A v4 call like `useQuery(someOpaqueExpression)` with a single argument that is neither a string, template literal, array, identifier-with-known-declaration, nor an object; calls with a second argument that is also not a function definition; calls already partially migrated into an unexpected shape.","commonSituations":"Codemod run against code with unusual key expressions (function calls, conditionals, spreads as the first arg); higher-order wrappers; code that built keys via helper functions.","solutions":["Open the cited file:start:end and rewrite the call into the v5 object form manually.","If the first arg is a dynamic expression, wrap it explicitly: `useQuery({ queryKey: [yourExpression], queryFn })`.","Re-run the codemod to handle other call sites; track this one for manual follow-up.","If the call is inside a wrapper that forwards args, refactor the wrapper first so the codemod can see concrete arguments."],"exampleFix":"// before\nuseQuery(buildKey(ctx))\n// after (manual)\nuseQuery({ queryKey: buildKey(ctx), queryFn: fetcherForCtx(ctx) })","handlingStrategy":"try-catch","validationCode":"// Pre-check whether the first arg is convertible to a key.\nfunction isKeyConvertible(node: any): boolean {\n  return ['Literal', 'TemplateLiteral', 'Identifier', 'ArrayExpression'].includes(node?.type)\n}","typeGuard":null,"tryCatchPattern":"try { runRemoveOverloadsCodemod(file) } catch (e) { if (e.name === 'UnknownUsageError') manualQueue.push({ file, loc: e.message }) }","preventionTips":["Simplify the first argument of v4 query calls to literals/arrays/identifiers before running the codemod.","Refactor higher-order query wrappers so concrete arguments are visible at the call site.","Collect `UnknownUsageError` reports and triage each cited file:start:end manually.","Re-run the codemod after manual fixes."],"tags":["codemod","v5-migration","remove-overloads","manual-migration","ast"],"backgroundTag":null,"analyzedSha":"159982c80b844487054155c38ffc760fe4208daf","analyzedAt":"2026-08-12T16:21:52.822Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}