pnpm/pnpm · error · DeprecateError

{DeprecateError}

Error message

{DeprecateError}

What it means

UnpublishHttpError::Registry wraps a DeprecateError raised during an unpublish mutation (PUT to the package document / tarball DELETE). It is #[diagnostic(transparent)], so the message is the inner DeprecateError from `registry_operation_failed`/`write_error_for_status`, e.g. a registry rejection of the unpublish. The OTP session deliberately does not treat this arm as a one-time-password challenge; send_mutation unwraps it so the registry error is shown once without OTP-wrapper narration.

Solutions

  1. Check the status in the message: 404 - verify the package name and version exist; 403 - you likely lack rights or the version is past the unpublish window; use `pnpm deprecate` instead.
  2. For 401, refresh your auth: `pnpm login` or update the token in .npmrc.
  3. If unpublish is blocked by policy, deprecate the version (`pnpm deprecate <pkg>@<version> "message"`) rather than removing it.
  4. For 5xx, retry later.

Example fix

// before
pnpm unpublish my-pkg@1.2.3   // 403: outside unpublish window
// after
pnpm deprecate my-pkg@1.2.3 "broken release, use 1.2.4"
Defensive patterns

Strategy: try-catch

Validate before calling

// Confirm the version exists and you are authorized before unpublishing
let who = std::process::Command::new("pnpm").arg("whoami").output()?;
if !who.status.success() { return Err("not logged in to the registry".into()); }
let view = std::process::Command::new("pnpm")
    .args(["view", &format!("{pkg}@{version}", ), "version"]).output()?;
if !view.status.success() { return Err(format!("{pkg}@{version} not found; nothing to unpublish".into()); }

Try / catch

// Branch on status before deciding between retry, deprecate fallback, or abort
match run_unpublish() {
    Err(e) if msg_contains(&e, "403") => {
        eprintln!("outside unpublish window or forbidden; falling back to `pnpm deprecate`");
        run_deprecate(pkg, version)?;
    }
    Err(e) if msg_contains(&e, "401") => Err("re-authenticate: pnpm login".into()),
    Err(e) => Err(e),
    Ok(v) => Ok(v),
}

Prevention

When it happens

Trigger: Produced when the registry returns a non-2xx status for an unpublish mutation that is not an OTP challenge: 403 for packages published >72h ago without proper authorization, 404 for a nonexistent package/version, 401 for bad credentials, or 5xx registry failures.

Common situations: Trying to unpublish a version outside the registry's unpublish window, missing or expired npm token, unpublishing a package version that does not exist, or a registry policy forbidding unpublish of a package that others depend on.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors


AI-assisted analysis of pnpm/pnpm@e45f033222 (2026-09-22). Data as JSON: /api/errors/ac8d5957548578db. Report an issue: GitHub.

Appendix: source

Thrown at pnpm/crates/cli/src/cli_args/unpublish/mutation.rs:38

pub(super) struct MutationRequest<'a> {
    pub(super) method: &'a Method,
    pub(super) url: &'a str,
    pub(super) json_body: Option<&'a str>,
}

/// An HTTP-level failure of an unpublish mutation, handed to the
/// [`OtpSession`]. Only the [`Otp`](Self::Otp) arm is a challenge it acts on;
/// the rest propagate.
#[derive(Debug, Display, Error, Diagnostic)]
enum UnpublishHttpError {
    #[display("the registry requested a one-time password")]
    Otp {
        #[error(not(source))]
        challenge: OtpChallenge,
    },

    #[diagnostic(transparent)]
    Registry(#[error(not(source))] DeprecateError),
}

impl OtpError for UnpublishHttpError {
    fn as_otp_challenge(&self) -> Option<OtpChallenge> {
        match self {
            UnpublishHttpError::Otp { challenge } => Some(challenge.clone()),
            UnpublishHttpError::Registry(_) => None,
        }
    }
}

/// Send one mutation through the OTP session: the first attempt carries any
/// configured `--otp`; a 401 OTP challenge drives the interactive flow and
/// the request is retried with the obtained password, while any other 401 is
/// a plain authentication failure. Every other status is returned for the
/// caller to classify.
pub(super) async fn send_mutation<Sys: UnpublishHost, Reporter: self::Reporter>(
    mutation: &mut MutationContext<'_>,

View on GitHub (pinned to e45f033222)