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 `query-fn-aware-usage-transformer`. `transformArgumentToKey` returned null for the first argument, meaning it could not derive a `keyProperty`. Unlike the filter-aware transformer, this variant throws immediately because every query it handles is expected to have a derivable key.

Source

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

  const replacer = (path) => {
    const node = path.node

    try {
      // If the given method/function call matches certain criteria, the node doesn't need to be replaced, this step can be skipped.
      if (canSkipReplacement(node)) {
        return node
      }

      const keyProperty = v5Utils.transformArgumentToKey(
        path,
        node.arguments[0],
        config.keyName,
        filePath,
      )

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

      const parameters = [jscodeshift.objectExpression([keyProperty])]
      const createdObjectExpression = parameters[0]
      const secondParameter = node.arguments[1]

      if (secondParameter) {
        const queryFnProperty = transformArgumentToQueryFunction(
          path,
          secondParameter,
        )

        if (queryFnProperty) {
          createdObjectExpression.properties.push(queryFnProperty)

          const thirdParameter = node.arguments[2]

          if (utils.isObjectExpression(thirdParameter)) {

View on GitHub (pinned to 159982c80b)

Solutions

Open the cited file:start:end and convert the call to the object form manually, supplying an explicit `queryKey`.
Simplify the first argument to an array literal or string literal so the codemod can transform it, then re-run.
If a wrapper forwards arguments, inline a concrete key at the call site for the codemod to process.
Re-run the codemod after fixing; track remaining manual sites via the reported file:line.

Example fix

// before
useQuery(getKey(id), () => fetchById(id))
// after (manual)
useQuery({ queryKey: getKey(id), queryFn: () => fetchById(id) })

Defensive patterns

Strategy: try-catch

Validate before calling

// Determine whether transformArgumentToKey would succeed.
function canDeriveKey(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

Inline concrete key literals at query call sites before running the codemod.
Hoist helper-built keys into named `const` arrays the codemod can resolve.
Triage each cited `file:start:end` and migrate manually.
Re-run the codemod after fixes to confirm remaining call sites transform.

When it happens

Trigger: A v4 `useQuery`/`useInfiniteQuery` call whose first argument is not convertible to a key property — e.g. a function call, a conditional, a logical expression, a member expression, or a spread element; calls already wrapped in another helper that hides the key.

Common situations: Helper functions used to build keys; ternary-computed keys; keys derived from object properties; codemod run on partially-migrated or unusual code.

Related errors

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