Legacy updates and recovery
Prepare older installations for updates and recover safely when a change fails.
An older client installation can contain custom code, cloned modules, and core files from several releases. A module's version number alone does not establish that every page will work with its next major version.
Prepare a legacy installation
- Confirm the installation. Check the organization, HubSpot portal ID, and installation folder. If the existing installation still needs adoption, complete that process before using its backup tools.
- Create a fresh manual backup. Wait for completion, then check its date and file count. An old initial backup will not include all later client work.
- Record what matters. Note affected pages, custom modules, and behavior you need to preserve. If you will change page content or layouts, keep a separate recovery plan for those HubSpot edits.
- Review the change log and core requirements. Major releases can change markup, styling, and field definitions. A newer module may need newer core macros or CSS.
- Test away from the client's live installation when possible. A test page using the same module code does not isolate a module update from other pages that use that code. Use a separate test installation to isolate code changes.
- Make one related change at a time. Test the result before moving on to another module or core-file change.
Fresh pre-update backups are manual. Do not assume clicking Update, Major update, or a catalog version first saves the current files for you.
Understand the update safeguards
Safe bulk updates preserve files that need review and keep breaking major module changes separate. A major change requires its own confirmation. When a module needs newer core files, the update installs the clean ones first. Core files edited in HubSpot are left as they are, and the module update goes ahead.
These checks reduce risk, but they do not test all client-specific code. Updating required core files can affect other modules too. Take the backup before the update, so it covers the core files the update may change.
If an older release is missing from the catalog, preserve a backup of the actual installation. The app cannot recreate unavailable historical release files from a version number alone.
Recover after an unsuccessful update
Stop making further changes and let the current job finish or fail. An update can write some files before HubSpot rejects another. A failed package version switch does not advance the recorded package version, but some live files may already have changed. The old version label does not prove that the installation is untouched.
Choose the recovery scope based on what changed:
- Only one module changed: restore that module from a backup taken before the update.
- Core files and modules changed together: restore the installation from a backup taken before both changes.
- One isolated file changed: use its file backup when you know the other files remain compatible.
- Page field values or layouts changed too: file restore will not undo those edits; address them separately in HubSpot.
Restores do not automatically reverse themselves if something fails. Keep the selected backup, resolve the error, and retry when the installation is ready. Afterward, check representative pages before applying another update.
Troubleshooting
| What you see | What to do |
|---|---|
| No backups are available yet | Check that you opened the correct installation. Complete adoption if needed, then create a manual backup. A new backup protects the current state; it cannot recover an earlier state that was never saved. |
| A backup you expected is missing from a module or file's versions | It may not contain that module or file. Check when it was installed and compare the backup dates. |
| Backup queued or an unavailable action | A job is waiting or another operation is active. Wait for a terminal result before starting another change; do not treat queued as completed. |
| Backup creation or restore fails with a connection or permissions problem | Check the connected HubSpot account and resolve any reconnection or permission-update request. Retry after access is restored. |
| You can see backups but cannot restore or delete them | Ask an organization owner or admin with installation access to perform the action. |
| A module update left a core file at an older version | The core file was edited in HubSpot, so the update did not overwrite it. Review its diff in Files and back it up before you update it. |
| Restored files show Customized or need review | This can be expected. Captured custom files are not automatically treated as safe for the next update to overwrite. Review the differences first. |
| A new module is still present after a full restore | Files created after the backup are left in place. Restore does not delete them. |
| The old code is back but a page still looks different | Check newer page-field or layout edits, files outside the backup, and shared dependencies. A file restore is not a whole-portal reset. |
If a job appears stuck or recovery still fails, contact support. Include the portal ID, installation name, backup name and date, affected module or file, error message, and example page URLs. Do not delete the recovery point while troubleshooting.