How to Stop an AI Coding Agent From Inventing APIs

An AI coding agent that calls a method, hits an endpoint, or flips a config flag that never existed is not being careless. It is doing exactly what a language model does when it has no real evidence: producing the most statistically plausible line of code for a pattern it has seen a thousand times in training, whether or not that exact API is real. Stopping an AI coding agent from inventing APIs that don't exist is not a matter of a longer system prompt asking it to be careful. It works because you force a different behavior: require the agent to quote the exact function signature or documentation line it is relying on before that call goes anywhere near your codebase. No real quote, no merge.

A different failure than reinventing code you already wrote

This is a distinct failure mode from an agent reinventing code that already exists in your repository, covered in stop an AI coding agent from reinventing existing code: that problem is an agent failing to notice a helper you already wrote and writing a near duplicate. This one runs the other direction. The agent is not duplicating something real, it is confidently inventing something that was never real anywhere, not in your code and not in the library it claims to call.

Why an AI coding agent ends up hallucinating methods

A language model has no live connection to the library you are using. It carries a compressed memory of thousands of codebases, across many versions of many libraries, blended into one set of weights. Ask it for a way to cancel a subscription, paginate a query, or expire a cache key, and it reaches for the shape of code it has seen most often for that kind of task, not a verified lookup against the exact package installed in your project. Most of the time the shape it reaches for matches the real API, because libraries tend to converge on similar naming. The rest of the time, it produces a method name from a different version, a different language, or a different library entirely, written with exactly the same confidence as the real one.

This is the same underlying mechanism behind an AI coding agent hallucinating methods it has never verified, or an agent inventing a whole package that does not exist rather than just one method inside a real one. The model is not lying and it is not being lazy. It is filling a gap with its most likely completion, and a plausible completion is indistinguishable from a real one until someone checks it against the actual source.

The grounding technique: make it quote the source before it ships

The single change that catches most of these before they reach a pull request is a one-line addition to your prompt or AGENTS.md: before calling any method, endpoint, or flag you have not already used elsewhere in this codebase, quote the exact signature or documentation line you are relying on, then write the call. This is an AI agent grounding technique in the literal sense, it grounds the next line of code in a real, checkable source instead of a remembered pattern. An agent required to produce a quote either finds one, in which case the API is probably real, or it cannot find one, in which case it tends to stop and say so instead of inventing the call anyway.

2. Point the agent at where to look. If your dependencies are vendored or docs are offline, tell it to read the installed package's type definitions or source directly instead of guessing from memory.

3. Treat a missing quote as a stop signal. An agent that cannot produce a real quote for a call it wants to make should say so and ask, not ship the call anyway with reasonable-sounding confidence.

4. Ask for the quote as a comment above the call during the session, not just in chat. A comment naming the doc line that justified the call is still there at review time, a chat message is not.

Add this alongside your other standing rules for these tools. Our AI coding tools guide covers the wider set of practices that keep an agent's output reviewable instead of just fast.

Before and after: a fabricated Prisma call caught by the check

Here is a case that shows up often in TypeScript codebases where the agent's training leans heavily on a different framework's conventions. Asked to fetch a user or throw if none exists, an agent wrote this against a Prisma client:

const user = await prisma.user.findOrFail({ where: { id } })

This looks entirely reasonable. findOrFail is a real, common method, just not on Prisma's client. It exists on Laravel's Eloquent models, User::findOrFail($id), a framework the model has seen enormously more of in training than your specific Prisma version. The call fails at runtime with "prisma.user.findOrFail is not a function", and if your test suite does not exercise this exact path, that failure ships to production.

With the grounding rule active, the same request produces a quote first:

Quote: Prisma Client Reference, User model: findUniqueOrThrow(args): Promise<User>, throws NotFoundError if no record matches the given arguments.

Then the call that is actually real:

const user = await prisma.user.findUniqueOrThrow({ where: { id } })

One extra step, a few seconds of lookup, and the fabricated call never reaches the pull request. The quote is not decoration, it is the check itself. An agent that can produce a real signature is calling something real. An agent that cannot is telling you, right there in the diff, that it is guessing.

A checklist for reviewing PRs for invented APIs

A fabricated call is not always just a runtime crash waiting to happen. A permissive-sounding invented flag can look enough like a real safety control to slip past a fast review, in the same spirit covered in how to catch an AI coding agent introducing a vulnerability. Run this checklist on any diff that calls something new:

• Every new method, endpoint, or flag the agent has not used elsewhere in the codebase has a quoted signature or doc line next to it, in a comment or the PR description.

• The quoted line actually appears in the installed package version. Verify AI generated code against real docs by opening the type definitions or the docs page yourself, not by trusting the quote at face value.

• Method and parameter names match the library's real casing and structure exactly. snake_case showing up in an otherwise camelCase SDK is a strong tell.

• The call is exercised by a test, not just accepted by the compiler. TypeScript and most linters happily accept a method that exists on some type in scope, they do not confirm it exists on the library's real client at runtime.

• No new call was copied from a different major version of the same library. A method removed two versions ago behaves exactly like one that never existed, for the version you have installed.

• Any config flag or endpoint parameter the agent introduced has a matching entry in your actual configuration schema or API reference, not just in the agent's own explanation of why it added it.

Once you catch an invented call in review, write it up the same way you would any other agent defect: the exact prompt, the fabricated call, and the real one it should have produced. Our guide on how to write a bug report for an AI coding agent covers the format that actually gets these fixed at the source instead of quietly worked around.

Frequently asked questions

How do I know if my AI coding agent is hallucinating a method?

Grep your installed dependency for the exact method name it just called. If the name does not appear in the package's type definitions, source, or changelog for the version you have installed, it is invented. Runtime errors like "is not a function" or "unknown parameter" are the most common way this surfaces after the fact.

Why does an AI coding agent hallucinate methods instead of saying it does not know?

A language model generates the most likely next token given everything it has seen, and a plausible method call is a more likely continuation than an admission of uncertainty, unless you have explicitly instructed it to prefer the second one. An AI coding agent hallucinating methods it never verified is a symptom of confident pattern completion, not an attempt to deceive.

Does telling the agent to "be careful" or "double check" stop this?

Rarely. A general instruction to be careful gives the model nothing concrete to check against, so it produces the same confident completion in a slightly more cautious tone. Asking for a specific, checkable artifact, the quoted signature or doc line, gives it something it can actually fail to produce when the API is not real.

Can I automate the grounding check instead of relying on manual review?

Partially. A CI step that greps new method calls against your installed package's type definitions catches many invented calls automatically, and failing the build when a called method cannot be found in the installed types is a reasonable backstop. It will not catch every case, particularly dynamically typed calls, so pair it with the checklist above rather than replacing review with it.

What if the agent invents an entire package, not just one method?

That is a related but distinct case, usually surfacing as a new line in package.json or requirements.txt for a package that does not exist on the registry at all. See our post on an AI hallucinating a package that does not exist for that specific failure and its fix.