Spotting Hallucinated APIs

Across the causeway lies the Hallucination Zone, where the stairs look solid until you step on them. AI assistants sometimes invent things that don't exist: a function, an option, a whole package. The invention looks exactly like the real thing, uses the right naming style, and is written with total confidence. That isn't the model lying. It predicts what code usually looks like, and "a function with this name ought to exist" is a very plausible prediction. Your job is to notice when you are standing on a stair to nowhere.

What a hallucinated API looks like

Hallucinations come in a few shapes:

• Invented functions: a method that sounds right but was never part of the language or library.
• Invented options: a real function called with a setting it doesn't support.
• Invented packages: an npm install for a package that was never published, or is something else entirely.
• Mixed versions: code that uses features from a newer version of a library than the one you have, or old ones that have since been removed.

// Looks plausible, but neither of these exists:
const name = user.name.capitalize();          // no String.prototype.capitalize
const res = await fetch(url, { retries: 3 }); // fetch has no retries option

// What actually exists:
const shown = user.name[0].toUpperCase() + user.name.slice(1);
const response = await fetch(url); // retrying means writing your own loop

The first line fails loudly with "capitalize is not a function". The second is sneakier. fetch ignores options it doesn't recognise, so the code runs without error and simply never retries. Invented options are often silent.

Check the official documentation

When a function or option is new to you, look it up in the official docs for the version you are using: MDN for JavaScript and browser APIs, the Node.js docs for Node, the library's own documentation site or README for packages. Search for the exact name. If it isn't there, treat it as invented until proven otherwise.

Don't confirm a hallucination by asking the same assistant "does this exist?". It may say yes just as confidently. Blog posts and forum answers can also be outdated or wrong. The official docs are the source of truth.

Check the package registry

Before installing a package an AI suggested, look it up on the npm registry or with npm view <name>. Check that it exists, that it is the package you think it is, and that it looks maintained: a real repository link, a sensible version history, and regular downloads.

This matters for security, not only for correctness. Attackers publish packages under misspelled versions of popular names (typosquatting, like expresss or lodahs), and some watch for package names that AI tools tend to invent and register them with malicious code inside. An install script can run on your machine the moment you install. A package that was published last week, has almost no downloads and no repository, but was confidently recommended by an AI, is a red flag.

Watch for version mismatches

Models learn from code written over many years, so they mix old and new. The code might use array.toSorted(), which needs Node 20 or later, when your server runs Node 18. Or it might use a library's old API that was removed two major versions ago.

Check the version you actually have (node --version, or the version in package.json) and read the docs for that version. If the AI's answer depends on a newer version, you have to either upgrade on purpose or ask for code that fits what you have.

Confirm with a tiny example

The fastest proof is to run it. Before building a feature on an unfamiliar function, try it on its own, in the Node REPL, the browser console or a scratch file:

console.log(typeof 'abc'.capitalize); // "undefined": it doesn't exist
console.log([3, 1, 2].toSorted());    // [1, 2, 3] on Node 20+, TypeError on older versions

For options, check that the behaviour actually changes. If you set a retry option, make the request fail and count how many times it's sent. A tiny experiment turns "I think this exists" into "I have seen it work."