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.
- Matches the failure to a likely cause below and suggests the fix.
Requires a connected agent. See Connect your agent.
By hand
Match the symptom to a cause. Each fix is one step.
| Cause | Symptom | Fix |
|---|---|---|
| Version held by the Minimum Age Policy | A brand-new upstream version won't install; the Feed serves the previous version meanwhile. | Wait out the configured window (24 hours by default) or lower the Feed's Minimum Age Policy. |
| Package blocked by a rule | An upstream package name is refused by an allow or block rule. | Allow the name — or remove the block — in Feed settings. |
| Version delisted | A version that used to resolve no longer does. | Pin a different version; delisting is deliberate, usually after a compromise. |
| Token expired, revoked, or wrong scope | A generic unauthorized response from the package client. | Issue a new Token scoped to the right Feed and purpose. |
| Wrong Feed URL shape | 404s or authentication failures against the Feed. | Use the Feed Base 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. |