What is an AI hallucination in code? When your agent invents things

What it actually is

An AI hallucination in code is when your agent writes something that looks completely normal (an import, a function call, a config key) but doesn’t exist. The thing itself is fictional, not a typo and not a logic bug in an otherwise real function. Your agent might call stripe.charges.createRefund() when the real method is stripe.refunds.create(), or add import { retryRequest } from 'fetch-retry-helpers' to a file: a plausible-sounding package that was never added to your project’s dependencies.

Think of it like a friend recommending a restaurant with total confidence: “Go to Luigi’s on 5th, it’s incredible.” They’re not lying to you. They’ve eaten at a hundred Italian places, and their memory blended the best details of several into one that never opened. Your AI does the same thing with code. It has seen thousands of libraries and APIs during training, and sometimes it produces a smooth blend of them that sounds exactly right and isn’t real.

Why your AI just did this

Language models write code by predicting what a plausible next piece of text looks like, not by checking a library’s actual source or documentation in real time. Give it a task that resembles a thousand things it’s seen before, and it fills gaps with the statistically likely answer: usually correct, occasionally a well-dressed guess. This shows up most when the library is new or niche (a small npm package released after training data was collected), when two libraries have similar-sounding methods and it merges them, or when a clean solution to your request doesn’t exist, so it builds one that “would make sense” if it did.

When you’ll run into it

• npm: Cannot find module 'xxx' or Module not found: Error: Can't resolve 'xxx' after your agent adds an import for a package that was never added to package.json.
• Python: ModuleNotFoundError: No module named 'xxx' or ImportError: cannot import name 'foo' from 'bar'.
• At runtime: TypeError: xxx is not a function. The object is real; the method your agent called on it isn’t.
• You ask “why doesn’t this work” and your agent replies something like “you’re right, that method doesn’t exist in this version.” That’s a clear tell you caught a hallucination.
• Mid-project, when the agent references an environment variable, config key, or CLI flag that was never defined anywhere in your codebase.

What to check

• Before running new code, scan for import/require lines you don’t recognize and confirm the package is listed in package.json or requirements.txt, and that it exists on npm or PyPI.
• When you hit “is not a function” or “has no attribute,” open that library’s real documentation and confirm the method name and its arguments match.
• Ask your agent to run the code itself before you trust the fix: a hallucinated call fails fast the moment it executes.
• Watch closely with brand-new packages, libraries released after your model’s training cutoff, and version-specific methods. That’s where invented APIs cluster.
• If a fix for a nasty bug looks suspiciously elegant, run it before believing it. Elegant-but-fake is a common shape for a hallucinated method.

Say it like a dev

Instead of: “It doesn’t work, fix it.” Say: “The function it called does not exist. Check the library’s actual docs and confirm the real method name before rewriting this.”

Instead of: “Add refund handling.” Say: “Add refund handling, but confirm the exact Stripe method name in their docs first. I don’t want a hallucinated API here.”

Instead of: “Why is this failing?” Say: “It references a library I never installed. Is that package real, and if so, add it to package.json properly.”