traps

Known breakages for a library, filtered to the version you have installed, with severity and the fix.

A trap is a breakage someone hit and a reviewer reproduced: the symptom as observed, the version range it applies to, and the fix. traps is the cheapest call in the set and the one worth making before you write code against a version you have not used before.

Arguments

Name	Type	Limits	Required	Default
`library`	string	1 to 80 characters	one of `library` or `id`	none
`version`	string	1 to 40 characters	no	all ranges
`id`	string	1 to 64 characters	one of `library` or `id`	none

id wins when both are passed. library matches a node by slug, by package name, or by display name, all case-insensitively, so better-auth, Better Auth and the npm name all reach the same row.

version is coerced with semver, then each trap is kept when its range is * or when the coerced version satisfies it, prereleases included. A version string semver cannot read is treated as no version at all, and you get every trap for the library.

Request

tools/call params

{
  "name": "traps",
  "arguments": { "library": "better-auth", "version": "1.7.3" }
}

Response

TRAPS Better Auth 1.7.3 (2)
  [622e042e] major >=1.0.0: Role or plan changes do not reach the session until the cookie cache expires (default 5 minutes).
  [90232128] minor >=1.0.0: Drizzle adapter cannot find plugin tables (organization, apikey) and fails at runtime, not at build.
pass id for the full fix
remaining: 52

Rows are sorted by severity: blocker, then major, then minor. At most eight print, and when there are more the header says so, as TRAPS Better Auth (8 of 14). The bracketed value is the first eight characters of the trap's identifier.

A library the corpus knows but has nothing verified against your range answers in one line, and it is a different answer from silence:

TRAPS Better Auth 1.7.3: none verified for this range.
remaining: 51

A library nobody has written about answers:

no traps recorded for "some-package" yet. Hit one? submit_trap sends it to review.
remaining: 50

One trap in full

Pass id to get the fix and the evidence link:

TRAP 622e042e Better Auth >=1.0.0 · major
SYMPTOM Role or plan changes do not reach the session until the cookie cache expires (default 5 minutes).
FIX Disable `session.cookieCache` for role-gated apps, or call `auth.api.getSession` with `disableCookieCache: true` on the routes that check roles, and invalidate the session on role change.
VERIFIED 2026-09-08
remaining: 49

The EVIDENCE line appears between FIX and VERIFIED when the trap carries a link; the two traps above do not. FIX is cut at 2,400 characters.

id accepts the full identifier or the eight characters the listing prints. The same symptom, fix, and evidence are on the library's page at wellworn.dev/traps/<library>.

Limit and error lines

Line	Cause
`pass library (and optionally version) or id`	Called with no arguments. Both are optional in the schema, so this check happens in the tool.
`no trap with id …`	The id is a well-formed identifier that matches no row.
`internal error (ref …); try again in a moment`	The tool threw. Retry once; if it repeats, send the ref.
`limit reached: …`	The window is spent. Limits.

What to do with the answer

Apply the fix in the same edit as the dependency, not after the symptom shows up. A blocker row means the version you are installing does not work for that use; pick another version rather than coding around it. Nothing here is speculative: if a trap is listed, someone reproduced it at that range.

For hooks, CI steps and shell scripts, the same text is one GET away without an MCP client. See the traps API.