---
title: "Fix a failing install | PackageMaze docs"
description: "From a failing install to the cause in minutes: policy holds, blocked packages, Token problems, and configuration mistakes, each with a fix."
canonical: https://www.packagemaze.com/docs/fix-a-failing-install/
---

> Documentation index: https://www.packagemaze.com/llms.txt

# Fix a failing install

Go from a failing install to the cause in minutes — whether it's a policy hold, a blocked package, a Token problem, or a configuration mistake.

## With your agent

> Tell your connected agent: "Why did last night's install fail?"

- Pulls the CI run's report — the token exchanges, resolutions, and install attempts PackageMaze saw.
- Reads the client's own error text for the package and version, then matches the failure to a likely cause below and suggests the fix.

> **Note:** A version the Feed does not serve is held or refused by a Feed policy. Never install it from another registry or add an index; use the newest version the Feed serves and tell the person what is held and until when.

Requires a connected agent. See [Connect your agent](https://www.packagemaze.com/docs/connect-your-agent/).

## By hand

Match the client's error text to a cause. Each fix is one step. When a Feed rule refuses an npm request, npm's error line carries `PackageMaze refused` and names the Policy, the version, and when a hold ends; pip and uv print only the status.

| Cause | Symptom | Fix |
| --- | --- | --- |
| Version held by the Minimum Age Policy | A brand-new upstream version is missing from the Feed's index; the Feed serves the previous version meanwhile. npm prints `code ETARGET` and `No matching version found for <package>@<version>`, pnpm `ERR_PNPM_NO_MATCHING_VERSION`, pip `No matching distribution found for <package>==<version>`, uv `there is no version of <package>==<version>`. When a lockfile already pins the held version, its fetch answers 404 and npm prints `PackageMaze refused <package> <version> on Feed <organization>/<feed> because the Feed's Minimum Age Policy has not released this upstream Package Version yet; the hold ends at <time>`; pip and uv print only the 404. | Pin the newest version the Feed serves and say when the hold ends (24 hours after the upstream publish by default). Do not add another registry or index. |
| Version refused by a Feed Policy | The License, Install Scripts, Native Code, Attestation, Distribution Format, or Yanked Artifact Policy leaves a version out of the index, with the same client lines as a hold. A pinned fetch's 404 names the Policy, for example `because the Feed's License Policy does not allow the package's declared license`. | Pin a version the Policy allows. An Organization Admin can change the Policy or exempt the package in Feed settings. |
| Package blocked by a rule | An upstream package name is refused by an allow or block rule. npm prints `code E404` and `404 Not Found - GET <Feed URL><package> - PackageMaze refused <package> on Feed <organization>/<feed> because the Feed's upstream policy does not serve this package`; pip prints `No matching distribution found for <package>` with `(from versions: none)`; uv prints `<package> was not found in the package registry`. | Allow the name — or remove the block — in Feed settings. |
| Version delisted | A version that used to resolve no longer does, with the same client lines as a hold. A pinned fetch's 404 reads `because the Package Version is delisted from the Feed`. | Pin a different version; delisting is deliberate, usually after a compromise. |
| Token expired, revoked, or missing Feed access | npm prints `code E401` and `Unable to authenticate, your authentication token seems to be invalid`. pip prints `No matching distribution found for <package>` with `(from versions: none)`, the same lines as a blocked package; uv adds `could not be queried due to a lack of valid authentication credentials (401 Unauthorized)`. | Rotate the Token or create a new Token with Read access to the right Feed. |
| Wrong Feed URL shape | npm prints `404 Not Found - GET <url>` with nothing after the URL; pip prints `No matching distribution found for <package>` with `(from versions: none)`. | Use the Feed URL with a trailing slash, `https://pkg.packagemaze.com/<organization>/<feed>/`. |
| pnpm ignoring committed placeholders | On pnpm 10.34.2+ or 11.5.3+, install is unauthorized despite an .npmrc credential placeholder. | Use user-level config or a CI temp npm config (`NPM_CONFIG_USERCONFIG`), not committed `${...}`. |
| CI missing id-token permission or access rule | setup-maze can't mint a Token in GitHub Actions. | Add `permissions.id-token: write` and the Feed's access rule; diagnose with `maze auth exchange-oidc --feed <organization>/<feed> --purpose install --format github-output`. |

Next: [Leaving PackageMaze](https://www.packagemaze.com/docs/leaving-packagemaze/)

Related: [Set up CI](https://www.packagemaze.com/docs/set-up-ci/), [See what's delivered](https://www.packagemaze.com/docs/see-whats-installed/)