ax-check rule

AXC-F005: Claimed package version does not exist

A manifest or install command pins a package version the registry does not have.

ax-check is a checker being prepared for release. This page documents the rule ahead of that release; see all 50 rules.

Severityerror
KindObserved. Depends on the program and environment at run time.
Modeax-check drift
Applies toInstruction files and manifests
Pattern tagsdrift, server-cards
Fix in one linePin a published version, or publish the version before the manifest that names it.

The file pins an exact version of a package, and the package exists, but the registry has no such version. This happens when a manifest is written before a release, or when a release is yanked or mistyped. An install that uses the pin fails.

What it checks

ax-check finds exact version pins in three places:

  • npm: name@1.2.3 in install and run commands, for example npx invoicekit-mcp@2.4.0.
  • PyPI: name==1.2.3 in install and run commands.
  • Manifests: packages[].version in a server.json, next to registryType and identifier.

For each pin it asks the npm registry or the PyPI JSON API for the package’s published versions. The rule fires when the package exists and the pinned version is not among them. If the package itself is missing, the finding is AXC-F003 or AXC-F004 instead.

Why it matters

A pinned version is a promise that a specific release exists. A server card or MCP manifest is read by tools that install the package for the agent, so a wrong pin breaks setup before the agent does anything. The agent may then fall back to the newest version, which can differ from what the file author tested. Pins also drift naturally: a file is written for 2.4.0, the release plan changes, and the file stays behind.

How to fix

  • Pin a version that is published. Look it up on the registry.
  • If the version is not yet released, publish it before you publish the manifest that names it.
  • If you do not need an exact pin, remove it and let the install use the latest release, accepting that later releases may behave differently.

Example

Find it:

ax-check drift --online server.json

Before

{
  "name": "io.example/invoicekit",
  "description": "Create and list invoices.",
  "version": "2.4.0",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "invoicekit-mcp",
      "version": "2.4.0"
    }
  ]
}

The registry lists 2.3.0 and 2.3.1 for invoicekit-mcp, but not 2.4.0.

After

{
  "name": "io.example/invoicekit",
  "description": "Create and list invoices.",
  "version": "2.3.1",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "invoicekit-mcp",
      "version": "2.3.1"
    }
  ]
}

How ax-check detects it

The extraction and the rule logic are deterministic, but the result depends on what the registry answers at the time of the run, so the same file can give different findings on another day. JSON and SARIF reports record when and where the check ran. It looks only at exact versions. For npm it accepts MAJOR.MINOR.PATCH with an optional pre-release or build suffix, so 2.4.0 and 2.4.0-beta.1 are checked. Ranges and tags such as ^2.4.0, ~2.4, latest and next are ignored. For PyPI it reads the value after ==. For server.json it reads the version next to a package whose registryType is npm or pypi. It compares the pin with the versions that the registry lists: the keys of versions in the npm metadata, and the keys of releases in the PyPI JSON answer. The comparison happens only when the package was found; if the lookup failed, the result is AXC-F002.

Known limits:

  • A version that was published and later deleted or yanked may still be listed, depending on the registry.
  • Pins in other registries, such as OCI images or NuGet, are not read.
  • The top-level version of a server.json is the server’s own version, not a package pin, and is not checked.

Offline runs do not look up versions; AXC-F011 reports the count. To silence this rule, use --disable AXC-F005.

Sources

Records in the AX evidence register that share a pattern tag with this rule. A shared tag means the record is about the same pattern, not that it tests this rule. Read the evidence class before the number.