Troubleshooting
Read diagnostic codes and transaction outcomes before retrying an install.
Published v0.0.13 reports categorized install and dependency-operation diagnostics. Handled operational failures still exit with code 1. A nonzero exit can occur after a change has committed, so inspect the transaction message before retrying.
Common diagnostics
| Diagnostic | Next step |
|---|---|
LOCKFILE_MISSING | Create and review a lock through online install before replay. |
LOCK_MANIFEST_MISMATCH | Review manifest changes; restore matching inputs or deliberately install the changed manifest and review the lock diff. |
REGISTRY_AUTH_MISSING | Check the selected route's token-env in the install environment. Do not switch origins to bypass it. |
RESOLUTION_FAILED | Check supported ranges, aliases, workspace targets and peer providers. |
INTEGRITY_MISMATCH | Stop and investigate the archive/source mismatch. Do not enable the unverified-artifact exception as a repair. |
STORE_CONTENT_UNAVAILABLE | Check whether the missing source has a pinned HTTPS URL and registry-declared integrity. install --frozen can fetch and verify missing source trees; --offline cannot. Approved derived outputs require separately reviewed online rebuilding. |
PROJECT_BUSY or STORE_BUSY | Wait for the competing operation before retrying. |
RECOVERY_FAILED | Preserve the journal and affected files; resolve recovery before another mutation. |
Read the transaction result
A rollback restores prior state when recovery succeeds. A committed result with cleanup pending means the dependency change already happened; repeating it can perform another mutation. A recovery-required result needs inspection of the retained journal and affected paths. outdated normally leaves project dependency state unchanged, but can recover a previous interrupted operation first.
Diagnostics bound message size and redact HTTP credential and query data. That does not make arbitrary project or child output safe to publish.
Existing package-manager installations
Tapid rejects an unmanaged node_modules instead of replacing another package manager's installation. Evaluate in a separate checkout when possible. Before activation, preserve the manifest, existing locks and installation in a verified backup outside the activation path. Move the npm-managed tree out of the project, then follow npm lock import to preserve supported npm selections, or review the graph from an ordinary install.
Do not delete an active tree, retained journal or staging directory to bypass a recovery failure. Stop competing processes and inspect the transaction result first. Restoring an earlier lock alone does not restore its matching manifest and installation.
Older registry identities
Locks with noncanonical persisted origins, such as uppercase hosts or explicit default :443, fail replay rather than silently changing identities. Stop concurrent installs. Keep a separate verified byte-for-byte backup in a new backup location and review routing. Deliberately remove the incompatible original lock before running online tapid install; an existing incompatible lock is validated and rejected, not silently migrated. Compare every changed version, origin, digest and edge. Run tapid lock verify and frozen replay against the verified store before adopting the replacement. This re-resolves the graph; it does not preserve the old selection automatically.
If the old exact graph must remain or the original registry is unavailable, stop. Do not edit registry strings or drop colliding entries to force replay. The tagged recovery procedure explains the boundary.
Incomplete locks and missing trees
tapid ci requires locked artifact URLs even with a warm cache or --offline. Regenerate an otherwise supported incomplete lock with a deliberate tapid update using live metadata, then review the full graph diff. Ordinary install replays a matching lock and does not automatically refresh it. A readable registry fixture can supply every URL-less locked identity for tests and air-gapped development.
Frozen hydration verifies missing sources; it does not repair corrupt local trees, bypass provenance checks or rebuild approved derived outputs. Restore verified prerequisites or investigate the failure before another mutation.
Containment failures
A missing profile or unsupported requested guarantee stops tapid run before launch. Check platform scope and the exact profile. Do not widen permissions or substitute an unrestricted runner automatically.
For published machine-readable outcomes, read JSON results.