Skip to content
Source
Sign inSign up

Report a bug upstream

Issues and pull requests / Issues

Report a bug in a package you use

Your coding agent works around a bug in an npm package and moves on, and the maintainers never hear about it. Have the agent report the bug on the package's repository on TanStack Source, with what it ran into, its workaround and the fix it proposes.

2 min read

Without a report, the next agent hits the same bug. The agent gives only the npm package name. TanStack Source finds the repository that publishes the package, so the agent does not need to know where it lives.

You need a token that is not scoped, or an agent session token. A scoped token cannot send a report, because the package's repository is not one of its repositories.

1. Make sure the package has a repository on TanStack Source

TanStack Source finds the repository from npm, the same way it finds the skills of your dependencies:

  • The repository field of the package on npm must point to a GitHub repository.
  • A public repository on TanStack Source must be verified as that GitHub repository. See Verify your GitHub repository.

If no repository matches, the report fails with <package> has no repository on TanStack Source. Nothing goes to GitHub.

2. Search for an open report first

When ten agents hit the same bug, one issue with ten comments helps the maintainers more than ten issues. Before the agent reports, it searches the open issues:

src search issues "null key" --repo tanstack/query --state open

If a report exists, the agent comments on it (src issue comment, or comment_on_issue in MCP). The MCP tool tells the agent to do this.

3. Send the report

Every part is required: the package, the version, a title, what happened, the workaround and the proposed fix.

In a terminal, run:

src issue report-upstream \
  --package @tanstack/react-query \
  --version 5.62.0 \
  --title "useQuery throws on a null key" \
  --problem "useQuery({ queryKey: null }) throws TypeError: x is not iterable." \
  --workaround "Pass [] when the key is null." \
  --fix "Treat a null key as an empty key in hashKey."

The command prints the URL of the new issue.

In MCP, the tool is report_upstream_issue, with the arguments package, version, title, problem, workaround and fix.

With REST, send the same fields as JSON:

curl -X POST https://<your-host>/api/v1/upstream-issues \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"package":"@tanstack/react-query","version":"5.62.0","title":"useQuery throws on a null key","problem":"...","workaround":"...","fix":"..."}'

The answer is 201 with owner, repo, number and htmlUrl of the new issue.

Done

  • The issue opens on the package's repository, by the person who owns the token, as any other issue.
  • Its body has the same sections every time: the package and version, What happened, Workaround and Proposed fix. Maintainers can read many reports quickly.
  • The repository's rules for new issues apply, so a report can wait in screening for a maintainer.