The Agent Knows the Library. Just Not Your Version.

The suggested API is real. The documentation example is valid. The project still cannot use it.

I find that more interesting than a completely invented method name. A believable solution can belong to a different version, package entry point, runtime or feature mode. It survives a quick recognition check because an engineer has seen something similar before.

The agent may know the library. The task requires it to know the library as installed and configured here.

Familiarity is not a compatibility check

A package name is a broad label. Several major versions can coexist in active projects, and a migration guide can describe a destination rather than the current state.

Even a matching version number may not settle the question. A package can expose different browser and server entry points. A feature may require configuration. A workspace package may resolve to a local artifact rather than the registry version the agent searched for.

This isn't a reason to distrust documentation. It is a reason to identify which documentation applies.

I would first establish the relevant installed package, its resolution from the consuming application and the configuration that changes its behavior. Only then would I decide whether the proposed example is evidence or inspiration.

Inspect what the application resolves

For a Node-based project, an inspection script placed next to the application's package.json can make the question concrete:

import { createRequire } from 'node:module';

const requireFromApp = createRequire(new URL('./package.json', import.meta.url));
const packagePath = requireFromApp.resolve('next/package.json');
const installedPackage = requireFromApp('next/package.json');

console.log(JSON.stringify({ packagePath, version: installedPackage.version }, null, 2));

This example checks Next.js metadata through Node's resolution from that application location. It doesn't inspect every conditional runtime export. Some packages don't expose package.json through their exports, so the same inspection method isn't universal.

The important part is the starting point. Resolving a package from the monorepo root may answer a different question from resolving it inside the application that imports it.

For a browser bundle, I would also inspect the relevant bundler configuration or output when aliasing and conditional resolution matter. A convenient Node probe isn't proof of what every runtime loads.

A manifest range describes intent. An actual resolution tells us more about the artifact being examined.

Current documentation can describe more than one model

Next.js provides a useful present example without needing a claim that its framework is unusually confusing. Its caching guide for projects without Cache Components, checked on October 23, 2026, explicitly identifies itself as the previous model and distinguishes the Cache Components path introduced in version 16.

That means searching for caching guidance isn't enough. The agent needs to establish the project's version and selected mode before transferring advice.

I am not upgrading this site or recommending one caching mode in this article. The point is that two official explanations can be correct while applying to different configurations.

The same pattern appears with router modes, compiler settings and server/client boundaries. Advice from a new guide may require a migration that is outside the current task.

An agent should not quietly perform that migration merely to make its preferred example fit. Discovering that a solution requires an upgrade is useful output. It is not automatic authorization to upgrade.

Types narrow the question, but don't finish it

A compiler rejecting an unfamiliar option is valuable feedback. Removing the error with a cast doesn't establish that the runtime supports the option.

I would inspect the installed declaration and the exported implementation around the disputed boundary. A type can be stale, overly permissive or describe an entry point different from the one actually used.

Likewise, a compiler accepting an option doesn't prove its intended behavioral effect. Some configuration paths tolerate extra input; some features are available only under particular runtime conditions.

The next check should discriminate between those possibilities. That might be a narrow runtime probe, a version-matched example or a test through the actual deployment adapter. Re-running the whole suite without exercising the disputed behavior may add time without resolving the uncertainty.

This is one place where I would rather have an agent say the evidence is incomplete than confidently widen a type until the build becomes green.

Upgrade instructions are not current project instructions

A migration document often says to replace one function with another or remove an old configuration field. Those instructions are conditional on performing the migration.

If the task is a bug fix on the existing release, copying the destination's code can create an accidental mixed-version implementation. It may even look cleaner than the valid old API.

I would keep the task's compatibility target explicit. Are we fixing behavior on the current version, preparing a migration, or completing an approved upgrade? Each has a different acceptable diff.

Related packages need attention too. A new plugin, shared component package or framework adapter may have peer requirements that the application doesn't satisfy. Satisfying one import doesn't establish a supported dependency set.

The versioned npm ci documentation describes frozen installation and configuration requirements for that CLI line. It helps explain why a manifest edit, lockfile resolution and installation can diverge. It is not permission to apply npm 11-specific behavior to another package manager without checking.

Keep retrieval attached to the compatibility question

I would search with the package version, relevant mode and disputed symbol rather than ask broadly how to use the library. Then I would compare the retrieved claim with the installed artifact.

If an MCP documentation tool exposes version selection, use it deliberately. If it returns only current documentation, retain that limitation. A successful tool call doesn't establish that the returned guide matches the consuming application.

Pinned documentation can age too. A project may have upgraded while its instructions still point to an earlier guide. Repository memory is useful for locating the intended source, not for overriding current package evidence.

The instructions-upkeep article concerns rules that stop describing the project. Dependency advice can fail in the same quiet way: the sentence remains plausible while its compatibility conditions have changed.

A useful answer includes the boundary

When an agent recommends an API, I want to know which package, version, entry point and configuration support the recommendation. The detail should match the risk; a familiar stable helper doesn't require a research report.

When compatibility is uncertain, a small verified alternative may be better than pulling the whole project toward the newest documentation. When an upgrade is genuinely necessary, make it a deliberate proposal with its own validation.

I don't want an agent that knows fewer libraries. I want one that can stop recognizing and start checking when recognition is no longer enough.

Which version-dependent mistakes are hardest to catch in your AI-assisted work: APIs from another release, features behind configuration, or packages resolved from the wrong workspace? I'd be interested in the smallest check that reliably settles the question for you.