TanStack/query · warning · UnknownUsageError

The usage in file "${filePath}" at line ${start}:${end} coul

Error message

The usage in file "${filePath}" at line ${start}:${end} could not be transformed into the new syntax. Please do this manually.

What it means

`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.

Source

Thrown at packages/query-codemods/src/v5/remove-overloads/transformers/filter-aware-usage-transformer.cjs:156

       * @type {import('jscodeshift').Property|undefined}
       */
      const keyProperty = v5Utils.transformArgumentToKey(
        path,
        node.arguments[0],
        config.keyName,
        filePath,
      )

      /**
       * The first parameter couldn't be transformed into an object property, so it's time to throw an exception,
       * it will notify the consumers that they need to rewrite this usage manually.
       */
      if (!keyProperty) {
        const secondArgument =
          node.arguments.length > 1 ? node.arguments[1] : null

        if (!secondArgument) {
          throw new UnknownUsageError(node, filePath)
        }

        if (utils.isFunctionDefinition(secondArgument)) {
          const originalArguments = node.arguments
          const firstArgument = jscodeshift.objectExpression([
            jscodeshift.property(
              'init',
              jscodeshift.identifier(config.keyName),
              originalArguments[0],
            ),
            jscodeshift.property(
              'init',
              jscodeshift.identifier(config.fnName),
              secondArgument,
            ),
          ])

          return jscodeshift.callExpression(node.original.callee, [

View on GitHub (pinned to 159982c80b)

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.

Example fix

// before
useQuery(buildKey(ctx))
// after (manual)
useQuery({ queryKey: buildKey(ctx), queryFn: fetcherForCtx(ctx) })

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check whether the first arg is convertible to a key.
function isKeyConvertible(node: any): boolean {
  return ['Literal', 'TemplateLiteral', 'Identifier', 'ArrayExpression'].includes(node?.type)
}

Try / catch

try { runRemoveOverloadsCodemod(file) } catch (e) { if (e.name === 'UnknownUsageError') manualQueue.push({ file, loc: e.message }) }

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of TanStack/query@159982c80b (2026-08-12). Data as JSON: /api/errors/5c1ae7b8f061d77f. Report an issue: GitHub.