AgentRules.org
Stack Builder
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
Fatal LLM Code Generation Signatures

AI Coding Hallucination Root Causes & Verified Fixes

Why frontier LLMs (Claude 3.5 Sonnet, GPT-4o, Cursor, Windsurf, Copilot) persistently generate deprecated APIs, breaking imports, and severe production vulnerabilities—and how deterministic negative constraint rules eliminate them.

6 Fatal Signatures Cataloged
100% Invariant Elimination via AgentRules
Compiler Traces & AST Gate Verified
Next.js 15Breaking change introduced in Next.js 15.0.0 (Oct 2024)
High Production Severity
Next.js 15 cookies() / headers() Should Be Awaited
Observed Runtime / Compiler Error
Error: Route used cookies() without await. cookies() is now an asynchronous function in Next.js 15.
Observed Symptom:Unhandled Promise Rejection or empty cookie values in Server Actions and Route Handlers.
LLM Root Cause:Prior to Next.js 15, cookies() and headers() were synchronous helper getters. In Next.js 15, Vercel transitioned all request-bound data sources to Promises to support dynamic IO and concurrent streaming optimizations. LLMs trained on pre-Next.js 15 codebases persistently generate synchronous access.
Verified Defense:Next.js 15 App Router & Server Actions Standard
Post-Mortem & Fix Analysis
React 19Deprecated in React 19.0.0 (Dec 2024)
High Production Severity
React 19 forwardRef is Deprecated (Ref is Now a Standard Prop)
Observed Runtime / Compiler Error
Warning: Accessing forwardRef is deprecated. In React 19, ref is passed directly as a standard component prop.
Observed Symptom:Unnecessary wrapper boilerplates, TypeScript type errors with React.ForwardRefExoticComponent, and compiler de-optimizations.
LLM Root Cause:React 19 eliminated the need for forwardRef(). Functions now receive ref as a first-class prop alongside other props. Because LLM training sets contain millions of lines of legacy React 16–18 code, models reflexively wrap components in forwardRef().
Verified Defense:React 19 Compiler & Modern Hooks Architecture
Post-Mortem & Fix Analysis
Tailwind CSS v4New Oxide engine and CSS-first configuration (Tailwind v4)
High Production Severity
Tailwind CSS v4 @apply and tailwind.config.js Compatibility Failure
Observed Runtime / Compiler Error
CssSyntaxError: Cannot resolve @apply utility or missing tailwind.config.js configuration in pure CSS mode.
Observed Symptom:PostCSS build errors, missing custom colors, and bloated compiled stylesheets.
LLM Root Cause:Tailwind v4 is an all-in-one CSS-first engine. The legacy tailwind.config.js file is superseded by standard CSS @theme blocks and pure CSS variables. AI models repeatedly hallucinate module.exports = { theme: { extend: {} } } and excessive @apply usage inside global styles.
Verified Defense:Tailwind CSS v4 Modern Theme & Pure CSS Standard
Post-Mortem & Fix Analysis
FastAPI / Python AsyncFastAPI 0.100+ & Starlette Async Event Loop
High Production Severity
FastAPI Synchronous Blocking Call Inside Async Event Loop
Observed Runtime / Compiler Error
RuntimeError: Event loop is blocked / Task was destroyed while pending / p99 latency spike to 30,000ms.
Observed Symptom:FastAPI server freezes completely when handling 50+ concurrent requests.
LLM Root Cause:In Python asyncio, any synchronous I/O call (such as requests.get(), time.sleep(), or standard synchronous sqlite3 / psycopg2) halts the entire operating thread. Because FastAPI runs async def routes on the main event loop thread, one blocking call blocks all other concurrent requests.
Verified Defense:FastAPI & Pydantic v2 Async Concurrency Standard
Post-Mortem & Fix Analysis
Prisma ORM / Node.jsAll Prisma versions (4.x / 5.x / 6.x)
High Production Severity
Prisma Client ORM N+1 Query Loop in GraphQL / REST Handlers
Observed Runtime / Compiler Error
Database connection pool timeout / Fatal error: too many clients already connected.
Observed Symptom:Single page request issues 200+ SQL queries, saturating PostgreSQL connections and crashing MariaDB.
LLM Root Cause:When fetching nested relations (e.g. users with their recent orders), AI models routinely write an array map with await prisma.order.findMany() inside. This issues N individual network queries instead of a single batched SQL query.
Verified Defense:Node.js & Prisma ORM Anti-N+1 Query Optimization
Post-Mortem & Fix Analysis
Docker / KubernetesAll Docker & OCI container specifications
High Production Severity
Docker Container Defaulting to Root User Execution
Observed Runtime / Compiler Error
CIS Docker Benchmark Failure: Check 4.1 - Ensure that a user for the container has been created.
Observed Symptom:Security compliance rejection, privilege escalation vulnerabilities, and potential host takeover on container breakout.
LLM Root Cause:By default, Docker executes all processes as UID 0 (root) inside the container unless explicitly instructed otherwise. If an application contains a remote code execution vulnerability, an attacker achieves root access inside the container filesystem.
Verified Defense:Docker Multi-Stage & Non-Root Hardening Standard
Post-Mortem & Fix Analysis

Frequently Asked Questions: AI Code Generation Hallucinations

Why do coding models stubbornly output deprecated syntax despite modern instructions?

Frontier models are trained on millions of repositories containing code written between 2018 and 2024. For breaking releases like Next.js 15, Tailwind CSS v4, or React 19, the legacy patterns outnumber modern patterns in the weights by 10,000 to 1. Without explicit negative constraint rules (e.g. "NEVER use synchronous cookies()"), the model defaults to the statistical maximum likelihood in its weights.

How does AgentRules eliminate these failure signatures?

Each AgentRules file is structured with RFC-2119 invariant clauses (MUST, MUST NOT) and side-by-side negative and positive code examples. We compile these into the exact formats recognized by Cursor (.cursor/rules/*.mdc), Claude Code (CLAUDE.md), Windsurf (.windsurfrules), and Codex (AGENTS.md).

Can I report or contribute a new framework hallucination signature?

Yes! You can submit breaking patterns and verified negative constraint rules via our Community RFC Governance portal or open a pull request against our public repository.