What manual cleanup steps are required after a failed Meteor upgrade to prevent version conflicts?

To prevent version conflicts after a failed Meteor upgrade, you must manually remove the .meteor/local directory and the node_modules folder. While Meteor uses .meteor/versions as the source of truth for package versions, it does not automatically purge the filesystem of artifacts generated during a partially completed upgrade process.

Required Manual Cleanup Steps

If an upgrade is interrupted or fails, follow these steps to ensure a clean state before retrying:

1. Revert Versioning: Restore .meteor/versions to its last known stable state (via Git or backup). This ensures the toolchain attempts to install the correct versions.
2. Purge Build Cache: Delete the .meteor/local directory. This removes stale compiled assets and corrupted build artifacts that can cause persistent errors.
3. Clear NPM Dependencies: Delete the node_modules directory. A failed upgrade may leave a mix of incompatible NPM package versions that meteor npm install might not fully resolve.
4. Rebuild: Run meteor to trigger a fresh compilation and dependency installation based on the restored versions file.

Comparison: Manual Cleanup vs. Meteor Reset

Action	Effect on Database	Effect on Build Cache	Effect on NPM Modules
meteor reset	Wiped	Partial Clear	No Change
Manual Deletion	Wiped (if .meteor/local is deleted)	Full Purge	Full Purge

Technical Explanations and Assumptions

The node_modules Risk: Retaining node_modules after a failure can lead to version mismatches because the NPM lockfile may have been updated while the actual installed binaries in node_modules remain in a partial or inconsistent state. Manual deletion forces a clean resolution of the dependency tree.

The .meteor/local Risk: This directory contains the local MongoDB instance and the build cache. If the upgrade failed during the compilation of internal Meteor packages, the cache may contain bytecode incompatible with the target version, leading to runtime errors that meteor reset cannot fix.

Verification and Safety

To verify the cleanup, run the following in your project root:

rm -rf .meteor/local node_modules
meteor

Warning: Deleting .meteor/local permanently removes your local development database. Ensure you have a backup or that your data is hosted on a remote MongoDB instance before proceeding.

Diagnostic Detail Needed: Are you using a custom npm version manager (like NVM) outside of the Meteor-bundled Node version? This may change whether node_modules needs to be cleared manually or handled via the manager.