Skip to content

Diagnostics and troubleshooting

pnport 0.1.2 is available. Its diagnostics apply to the published CLI. Full filesystem/process compatibility remains incomplete. Check installation and known limits for unresolved macOS initialization and cancellation failures.

Start with doctor

Run pnport doctor for human-readable project, platform, injection, and cache checks. pnport doctor --json writes one schema-version-1 object to stdout with ready and typed checks. ready: false exits 125; ready: true does not guarantee that a specific executable can accept virtualization.

SymptomWhat to check
Project check failsConfirm an installed Yarn 4 PnP project and the selected .pnp.cjs; pnport does not repair it.
Dependency-view conflictResolve a physical node_modules collision yourself; pnport leaves it untouched.
Platform or injection is unsupportedUse a host and executable with a verified release capability; protected executables cannot be forced through pnport.
Archive or cache errorCheck that the installed package archive is intact and the private cache is writable; inspect cache management.
Graph-change restart noticeStop and start the command again after PnP data or an active archive changes.

Earlier 0.1.0 reports a dependency-view conflict for an empty or cache-only physical node_modules, including caches left by Vitest. Version 0.1.2 supports hidden tool-cache coexistence; see filesystem behavior. The doctor JSON schema and exit codes remain unchanged.

Exit codes and streams

StatusMeaning
2Invalid pnport arguments.
125pnport initialization, runtime, required restart, or non-ready doctor result.
126Command found but cannot be executed.
127Command not found.

When a child starts successfully, pnport passes through its exit status. On macOS, intermittent initialization and cancellation failures can return 125 instead of the expected signal-derived status; this remains unresolved in 0.1.2. Stable PNPORT_* codes on stderr distinguish a pnport failure from a child that exits with the same number. Normal missing files remain child-visible filesystem errors rather than always stopping the supervisor.

pnport diagnostics go to stderr; child stdout and stderr are inherited rather than captured. Default logging includes errors and necessary notices. --log-level debug can expose paths, so review debug logs before sharing them. pnport diagnostics must not contain file contents, environment values, full argument vectors, or captured child output. There is no pnport telemetry or hosted diagnostic service. Report a sanitized reproduction through GitHub Issues.