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

"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.

Requires a connected agent. See 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`.