TanStack/query · warning · UnprocessableKeyError

In file ${filePath} at line ${node.loc.start.line} the type

Error message

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.

What it means

Catch-all `UnprocessableKeyError` at the end of the v4 `key-replacer.cjs` transform. If the AST node for the key matched none of the recognized shapes (string literal, template literal, identifier with known declaration, array expression, object expression), the codemod cannot guess how to wrap it and asks the user to migrate manually, citing the line and the unresolved key name.

Source

Thrown at packages/query-codemods/src/v4/utils/replacers/key-replacer.cjs:66

      // When the node is an identifier at first, we try to find its declaration, because we will try
      // to guess its type.
      const variableDeclaration = findVariableDeclaration(node)

      if (!variableDeclaration) {
        throw new UnprocessableKeyError(
          `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.`,
        )
      }

      const initializer = variableDeclaration.value.init

      // When it's a string, we just wrap it into an array expression.
      if (isStringLiteral(initializer) || isTemplateLiteral(initializer)) {
        return jscodeshift.arrayExpression([node])
      }
    }

    throw new UnprocessableKeyError(
      `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.`,
    )
  }

  const createKeyProperty = (node) =>
    jscodeshift.property(
      'init',
      jscodeshift.identifier(keyName),
      createKeyValue(node),
    )

  const getPropertyFromObjectExpression = (objectExpression, propertyName) =>
    objectExpression.properties.find(
      (property) => property.key.name === propertyName,
    ) ?? null

  const buildWithTypeArguments = (node, builder) => {
    const newNode = builder(node)

View on GitHub (pinned to 159982c80b)

Solutions

Manually convert the call to the v4+ key-array form, e.g. `useQuery({ queryKey: [cond ? 'a' : 'b'], queryFn })`.
Simplify the expression to a `const` array literal so the codemod can transform it, then re-run.
Inspect the cited line and apply the v4 key-array convention by hand.
Run the codemod on simpler files first and address complex ones manually.

Example fix

// before
useQuery(getKey() || 'fallback', fetchFn)
// after (manual)
useQuery({ queryKey: [getKey() || 'fallback'], queryFn: fetchFn })

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check: is the key node one of the codemod's recognized shapes?
function isRecognizableKeyShape(node: any): boolean {
  return ['Literal', 'TemplateLiteral', 'Identifier', 'ArrayExpression', 'ObjectExpression'].includes(node?.type)
}

Try / catch

try { transform(file) } catch (e) { if (e.name === 'UnprocessableKeyError') manualQueue.push({ file, line: e.message }) }

Prevention

Reduce complex key expressions (calls, ternaries, member access) to array literals before codemod.
Run the codemod in small batches and review failures per-file.
Track each cited line in a migration checklist.
Hoist helper-built keys into named `const` arrays.

When it happens

Trigger: A query key node that is a `LogicalExpression` (`a || b`), a `ConditionalExpression` (`cond ? x : y`), a `CallExpression` (`getKey()`), a `MemberExpression` (`obj.key`), or any non-literal/non-identifier form; spread elements in arrays; binary expressions building keys.

Common situations: Dynamic key construction via helper functions; ternary-computed keys; keys referencing object properties; codemod run against code using non-trivial expressions in the key position.

Related errors

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