Use this list to identify a symptom, check its cause and verify a repair. The fifty entries are a practical troubleshooting index, not a statistical ranking of how often AI makes each mistake. Start with the first failing request or command, preserve its relevant error privately and reproduce it before asking for another code change.
Triage before editing
Record the expected behavior, actual behavior, affected environment and last working commit. Check the browser request and server log for the same action. Remove credentials and customer data before sharing diagnostics.
Make one bounded repair, run the failing case again and check a nearby success case. Do not install a package, disable authorization or replace a whole configuration just because an error message mentions it.
Build and compilation
| # | Symptom | Check and repair | Verify |
|---|---|---|---|
| 1 | Package cannot be found | Check spelling, installed version and whether it belongs to this workspace before installing | Locked clean install and build succeed |
| 2 | Local module missing | Match the real path and filename case; check exports | Build in the deployment environment |
| 3 | Property does not exist | Inspect the installed type or schema and use the supported field | Relevant type check passes |
| 4 | Adjacent JSX elements fail | Return a single enclosing element or fragment | Component compiles |
| 5 | Unexpected token | Inspect the reported line and preceding delimiters; check file syntax | Parser accepts the corrected file |
| 6 | Duplicate identifier | Find both declarations and retain the intended one | Imports and exports remain valid |
| 7 | Type is not assignable | Correct the contract or validate the input; avoid hiding it with any | Correct and invalid inputs are checked |
| 8 | Module format error | Match ESM/CommonJS across that file, package and runner | Start the affected command; do not flip the whole project blindly |
| 9 | JSX transform error | Check the compiler and JSX runtime configuration for the installed stack | A minimal affected component renders |
| 10 | Invalid hook call | Check hook placement and duplicate or mismatched React copies | Component renders through the failing path |
Keep project commands in the instruction file so the next session does not guess a different package manager or test runner.
Runtime and state
| # | Symptom | Check and repair | Verify |
|---|---|---|---|
| 11 | Reading an undefined value | Validate the response boundary; handle missing data explicitly | Empty, invalid and success cases |
| 12 | Hydration mismatch | Compare server and first client render; inspect dates, browser state and invalid HTML | No mismatch on a fresh load |
| 13 | Infinite rendering | Find the update cycle and remove unnecessary derived state or unstable dependencies | Updates stop after the intended action |
| 14 | State appears stale | Use the next value directly or a functional update when based on prior state | Two rapid actions give the right result |
| 15 | Interval or subscription persists | Return effect cleanup and cancel obsolete work | Leaving the route stops its activity |
| 16 | Recursive stack overflow | Add a correct termination condition and inspect cycles | Base and recursive cases terminate |
| 17 | Missing array element | Handle an empty list and validate indices | Zero, one and last-item cases |
| 18 | Pagination skips a page | Align index base, cursor and end-of-list contract | First, middle and final pages |
| 19 | Concurrent writes conflict | Enforce the invariant transactionally or with conditional writes | Simultaneous requests preserve stored data |
| 20 | Handler sees old values | Review closure dependencies and use a suitable functional update or current reference | Action uses the latest state |
| 21 | Date shifts a day | Decide whether the value is a calendar date or timestamp; preserve the distinction | Test more than one timezone |
| 22 | Money rounds incorrectly | Use integer minor units or a suitable decimal type with currency rules | Boundary and rounding examples |
| 23 | Special characters break input | Encode for the destination format; parameterize database queries | Quotes, Unicode and reserved characters |
| 24 | Styles override unpredictably | Inspect computed styles and remove competing ownership | Affected states work in both themes |
| 25 | Spinner never ends | Resolve success, error and cancellation paths explicitly | Slow, failed and completed requests |
For hydration, the Next.js explanation lists several causes; moving all rendering into an effect is not a universal repair. For concurrency, await in one request does not serialize other users' requests.
API and data
| # | Symptom | Check and repair | Verify |
|---|---|---|---|
| 26 | CORS blocks a browser request | Match allowed origins, preflight and credentials deliberately | Allowed origin works; an unintended origin does not gain access |
| 27 | Protected request returns 401 | Check the intended session or token lifecycle | Signed-in works; signed-out stays denied |
| 28 | API returns 404 | Check method, path, base URL and route deployment | Request reaches the expected handler |
| 29 | Rate limit returns 429 | Honor applicable retry timing; bound attempts, concurrency and total duration | Load falls rather than amplifies |
| 30 | JSON parsing fails | Check status and response content type before parsing | HTML error and valid JSON handled |
| 31 | Database times out | Inspect connection use, pooling and slow queries | Representative concurrent load completes |
| 32 | User input changes SQL meaning | Use parameterized queries and bounded privileges | Injection-like input remains data |
| 33 | Configuration missing | Validate required settings in the correct environment | Fresh production build or startup fails clearly when incomplete |
| 34 | Webhook signature fails | Check environment secret and exact raw-body verification requirements | Valid event accepted; tampered event rejected |
| 35 | JSON serialization fails | Map unsupported values to an explicit response contract | BigInt and missing-field cases handled deliberately |
Authentication and authorization
| # | Symptom | Check and repair | Verify |
|---|---|---|---|
| 36 | Login redirect loops | Exclude public entry and callback routes as appropriate | Login, callback and protected deep link |
| 37 | Session disappears | Check cookie domain, path, expiry, cross-site flow and SDK requirements | Refresh and callback work on the real domain |
| 38 | OAuth callback rejected | Match the provider's registered destination and allowed redirects | Preview and production tested separately |
| 39 | RLS returns no rows | Check grants, session, role and operation-specific policy | Owner succeeds and another account stays blocked |
| 40 | Session credentials exposed | Follow the framework's supported session design and protect against XSS/CSRF | Sensitive credentials stay out of URLs, logs and public assets |
| 41 | Another user's record accessible | Enforce resource ownership on the server or database | Substitute the other user's ID and confirm denial |
| 42 | Reset link reusable indefinitely | Use a short-lived, single-use recovery design | Expired and reused link cannot reset a password |
| 43 | Cross-site mutation succeeds | Apply the framework's CSRF protection and origin policy where required | Legitimate request works; forged cross-site action fails |
Cookie attributes depend on the authentication architecture; “make every cookie HttpOnly” can break an SDK that expects browser access. Follow the supported design and test it. Use two-user authentication checks and the Supabase RLS guide before relaxing a policy to fix an empty screen.
Deployment and operations
| # | Symptom | Check and repair | Verify |
|---|---|---|---|
| 44 | CI fails while local works | Match runtime, lockfile, variables, paths and installed framework version | Reproduce with a clean production build |
| 45 | Function exceeds its limit | Check the actual plan and runtime; bound work or use a supported job mechanism | Worst expected work stays within the recorded limit |
| 46 | Build runs out of memory | Identify the phase and memory-heavy inputs before changing limits | Build completes under the target allocation |
| 47 | Mixed-content warning | Replace unintended HTTP resources with supported HTTPS endpoints | No insecure request in the affected flow |
| 48 | Static rendering fails on runtime data | Choose the framework's supported rendering model for that route | Build and authenticated runtime behavior both work |
| 49 | Certificate invalid | Check domain ownership, DNS, hostname and certificate issuance | A normal browser establishes a valid secure connection |
| 50 | First request is slow | Measure cold and warm requests, dependency latency and compute work | Repeated measurements improve under the same conditions |
Do not bypass a browser certificate warning or assume waiting will fix a wrong hostname. An edge runtime is not a universal performance repair; it can change API compatibility and data-access latency.
Keep the fix from returning
For a meaningful bug, retain a regression check that fails for the original reason. For a visual fix, inspect the rendered result and affected states using the verification walkthrough. Record what passed and what remains untested.
Before releasing the change, run the deployment checklist. If requests can trigger paid model work, also check usage limits and API budgeting.