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
- Run `pnpm install` in the workspace root before publishing so every referenced project's manifest is fully populated.
- Check that `<dep>/package.json` contains the required fields (name, version) for the dependency referenced with `workspace:`.
- Verify the `workspace:` specifier points at a real workspace project (correct path/name in `pnpm-workspace.yaml` globs).
- 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
- Always run pnpm install before pnpm publish/pack in a workspace
- Validate all workspace package.json files in CI (name and version present)
- Keep workspace globs in pnpm-workspace.yaml in sync with the actual directories
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
- BATCH_PUBLISH_REQUIRES_RECURSIVE
- CatalogResolutionError
- ERR_PNPM_INVALID_WORKSPACE_CONFIGURATION
- ERR_PNPM_MISSING_REQUIRED_FIELD
- ERR_PNPM_NO_SCRIPT
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)