pnpm/pnpm · error · ReplaceWorkspaceProtocolError

CannotResolveWorkspaceProtocolError

Error message

CannotResolveWorkspaceProtocolError

What it means

This variant wraps `CannotResolveWorkspaceProtocolError` and is thrown by the exportable-manifest crate when rewriting `workspace:` dependency ranges into publishable versions. It fires when the dependency's directory was located, but its `package.json` lacked one of the fields required to derive the published version (name/version). Per the source docs, the most common reason is that the workspace project has not been installed yet, so the manifest fields pnpm relies on are absent.

Solutions

  1. Run `pnpm install` in the workspace root before publishing so every referenced project's manifest is fully populated.
  2. Check that `<dep>/package.json` contains the required fields (name, version) for the dependency referenced with `workspace:`.
  3. Verify the `workspace:` specifier points at a real workspace project (correct path/name in `pnpm-workspace.yaml` globs).
  4. Re-run the publish/pack command after fixing the manifest.

Example fix

// before: publish without installing
pnpm publish

// after: install first so workspace manifests are resolved
pnpm install
pnpm publish
Defensive patterns

Strategy: validation

Validate before calling

// before resolving workspace: specs, ensure the dep manifest is complete
const manifest = JSON.parse(fs.readFileSync(path.join(depDir, 'package.json'), 'utf8'))
if (!manifest.name || !manifest.version) {
  throw new Error(`${depDir}/package.json is missing name/version — run pnpm install first`)
}

Type guard

function isWorkspaceSpec(spec: string): boolean {
  return typeof spec === 'string' && spec.startsWith('workspace:')
}

Try / catch

try {
  await replaceWorkspaceProtocol(manifest)
} catch (err) {
  if (err.code === 'ERR_PNPM_CANNOT_RESOLVE_WORKSPACE_PROTOCOL') {
    console.error(`Run pnpm install before publishing: ${err.message}`)
    process.exit(1)
  }
  throw err
}

Prevention

When it happens

Trigger: Calling the workspace-protocol replacement during `pnpm publish`/`pack` for a dependency whose spec starts with `workspace:` while the referenced workspace package's manifest cannot yield the resolved version (missing name/version fields or missing manifest content).

Common situations: Publishing a freshly cloned monorepo without running `pnpm install` first; a workspace package with a hand-edited or incomplete `package.json`; a `workspace:` dependency pointing at a project whose manifest was generated or stripped.

Related errors


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

Appendix: source

Thrown at pnpm/crates/exportable-manifest/src/replace.rs:44

#[derive(Debug, Display, Error, Diagnostic, Clone)]
#[display(
    "Cannot resolve workspace protocol of dependency \"{dep_name}\" \
     because this dependency is not installed. Try running \"pnpm install\"."
)]
#[diagnostic(code(ERR_PNPM_CANNOT_RESOLVE_WORKSPACE_PROTOCOL))]
pub struct CannotResolveWorkspaceProtocolError {
    #[error(not(source))]
    pub dep_name: String,
}

/// Error envelope for both rewrite helpers.
#[derive(Debug, Display, Error, Diagnostic)]
pub enum ReplaceWorkspaceProtocolError {
    /// The dependency's directory was found but the `package.json`
    /// lacked one of the required fields. Most common reason: the
    /// project hasn't been installed yet.
    #[diagnostic(transparent)]
    CannotResolve(#[error(source)] CannotResolveWorkspaceProtocolError),

    /// Reading `<dep>/package.json` itself failed (malformed JSON, IO
    /// error other than ENOENT, ...). Propagated so the caller can
    /// surface the underlying cause.
    ReadManifest(#[error(source)] PackageManifestError),
}

/// Rewrites a single `dependencies` / `devDependencies` /
/// `optionalDependencies` value at publish time.
///
/// Returns `dep_spec` unchanged when it doesn't start with `workspace:`
/// so the caller can fold the helper into a generic per-field rewrite
/// without branching on the protocol.
pub fn replace_workspace_protocol(
    dep_name: &str,
    dep_spec: &str,
    dir: &Path,
    modules_dir: Option<&Path>,

View on GitHub (pinned to e45f033222)