> ## Documentation Index
> Fetch the complete documentation index at: https://docs.curator.interworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Upgrades

> Common upgrade issues and solutions to help resolve problems during the Curator update process.

Occasionally, you may run into issues during the upgrade process. We've provided some common scenarios and
how to quickly resolve them below.

**NOTE:** While running updates, it is always a good idea to have someone on standby during your upgrade who
has access to the server that Curator is running on, as most of these debugging solutions require
server-level access.

## Re-run the Upgrade With an Alternate Method

Curator can be upgraded in several different ways, so if you run into an issue upgrading in a specific way,
try using an alternative method to upgrade.

For example, there may be an issue with running the "one click" upgrade on your system.

Try upgrading via the Curator API, or using the Manual Upgrade method.

Both of these upgrade methods are detailed in our [System Upgrade Guide](https://docs.curator.interworks.com/upgrading_migration/upgrading/system_upgrade.md).

## Dependency Upgrades

If Curator requires dependency updates before upgrading, such as PHP, follow the steps provided in our
[dependency upgrades](https://docs.curator.interworks.com/upgrading_migration/upgrading/dependency_updates.md)
documentation.

## License Expiration Blocking Upgrade

When you start a one-click upgrade, Curator runs a set of pre-upgrade checks and shows the results in a
confirmation window. If your license check fails, that window is headed **"Caution! An issue was found"** and
lists:

> License Expiration **You will not be able to upgrade until this is resolved.**

When an issue blocks the upgrade, the **Upgrade** button is not shown in that window — only **Cancel**.

This is a license check, not a PHP or database check, so the fixes described elsewhere on this page do not
apply. Curator stores the expiration date that the InterWorks licensing service reports for the license key
saved on your instance, and blocks the upgrade when that date is in the past or when Curator has no expiration
date on record at all. A missing date is common when the stored key is absent or incorrect — for example after
a migration to a new server — or when a recent renewal has not yet been synced to the instance.

The **License Expiration** tile at the top of **Settings** > **Curator** > **System Upgrade** shows the date
Curator currently has on record, which tells you which of the two cases you are in.

> [!NOTE]
>
> On Curator SaaS, InterWorks manages your license and performs your upgrades, and the **Update Key** link is not
> shown. If you see this error on a SaaS instance, contact [Curator support](https://interworks.com/help).

**Step 1 — Reload the System Upgrade page:**

Curator re-syncs the expiration date from the licensing service each time the System Upgrade page loads.
Navigate to **Settings** > **Curator** > **System Upgrade** and let the **License Expiration** tile populate. If
it now shows a future date, retry the upgrade.

**Step 2 — Re-enter your license key:**

If the tile still shows no date, or reports your key as missing, re-enter the key by following the
[Updating License Key](https://docs.curator.interworks.com/site_administration/license_key/updating_license_key.md) guide. Saving the key clears
Curator's cache for you, so no separate cache clear is required. Return to the System Upgrade page afterwards so
the expiration date can sync, then retry the upgrade.

If the tile still shows stale information, clear the cache explicitly using the **Clear Cache** button in the
backend, or by appending `?cache=clear` to any Curator page URL while signed in to the backend, and reload the
System Upgrade page.

**Step 3 — Check whether the license has actually lapsed:**

If the tile shows a real expiration date that has already passed, your subscription has lapsed and re-entering
the same key will not clear the block. Contact your account manager to renew, then repeat Step 1 so the renewed
date syncs to your instance.

If the error persists after the steps above, contact [Curator support](https://interworks.com/help) with the
exact error text, your Curator version, and the URL of the instance. Do not post your license key in a public
channel.

## Curator Upgrade Failing After a PHP Upgrade

If you upgraded PHP on your server independently and the Curator upgrade now fails, a PHP version mismatch is
the most likely cause. Each Curator release supports a specific range of PHP versions, and running outside that
range causes runtime errors.

This scenario is easy to miss because the System Upgrade page only checks whether your PHP version is *too old*
for the release you are installing. It does not warn you when your PHP version is *newer* than the release
supports. If you upgraded PHP past the maximum version supported by your **currently installed** Curator
release, that release starts throwing runtime errors — including while it is running the upgrade — with no
version warning shown.

**Step 1 — Check your current PHP version:**

Run `php --version` on your web server. If you cannot access the server, log in to the backend of Curator and
navigate to **Settings** > **Curator** > **Status**, where the PHP version is listed for self-hosted instances.

**Step 2 — Compare against the supported PHP range:**

Refer to the
[PHP compatibility table](https://docs.curator.interworks.com/upgrading_migration/upgrading/dependency_updates.md#php-dependencies-by-curator-version)
and check your installed PHP version against **both**:

* the release you are currently running, since that code is what performs the upgrade, and
* the release you are upgrading to.

**Step 3 — Resolve the mismatch:**

* If your PHP version is **above the maximum** supported by your currently installed Curator release: downgrade
  PHP to a version within that release's supported range, complete the Curator upgrade, and then re-apply the
  PHP upgrade once you are on a Curator release that supports it. This restores the normal order of operations —
  Curator first, PHP second, or PHP first only when the release you are on already supports it.
* If your PHP version is **below the minimum** supported by the release you are upgrading to: follow the
  [Dependency Updates](https://docs.curator.interworks.com/upgrading_migration/upgrading/dependency_updates.md) guide to upgrade PHP into the
  supported range. In this case the System Upgrade page will also show a **"PHP X.X+ Required"** warning on the
  release.
* If you are unsure which direction the mismatch runs, contact
  [Curator support](https://interworks.com/help) with your PHP version, your current Curator version, and the
  version you are trying to upgrade to, and we can advise on the safest path forward.

Once PHP is inside the supported range, retry the upgrade using any of the methods described in the
[System Upgrade Guide](https://docs.curator.interworks.com/upgrading_migration/upgrading/system_upgrade.md). If errors persist, capture the event log
using the [Event Log Troubleshooting](#event-log-troubleshooting) steps below and send it to Curator support.

## Updating the Curator Database (Running Migrations)

> [!NOTE]
>
> Curator returns **503 Database Error: Check Curator Logs to Resolve** when a database query fails during a web
> request. Unfinished migrations are one cause after an upgrade. The steps in this section re-run them. On
> Curator SaaS, InterWorks hosts your instance. Send the error to
> [Curator support](https://interworks.com/help) instead.

Curator's database is often modified during the upgrade process, and if database changes are not completed
successfully database errors can occur.

If you run into any database errors after upgrading, or during the upgrade process, re-running Curator's
database migrations can resolve these errors.
You can safely rerun these migrations multiple times without any adverse effects.

**To Re-run the Curator Database Migrations From Your Browser:**

1. Sign in to the Curator backend.
2. In the same browser, visit your Curator URL with `/up` added to the end, for example:
   `https://curator.example.com/up`. If you are not signed in to the backend, the page is not found and no migrations run.
3. You should be directed to a page that contains "success" followed by a list of the steps taken to finish
   the migration. If you see errors instead, make note of the errors seen and contact Curator support for
   further assistance.

**To Re-run the Curator Database Migrations From the Web Server:**

1. Open a command prompt/terminal.
2. *Double-check* that you are running the terminal/command prompt as the same user that is running Curator
   (you can find this information on the backend of Curator under **Settings** > **Curator** > **Status**).
3. Use the `cd` command to move the command prompt into your webroot (e.g. `cd /var/www/html` on Linux or
   `cd C:\InterWorks\Curator\htdocs` on Windows).
4. Type `php artisan winter:up` and then press ENTER.
5. Any remaining database migrations will run, and display status messages in green.
6. If there are any errors during this process, please take a screenshot and send it to Curator support.

## File System Permissions Issues

If Curator's logs contain errors relating to filesystem permissions on your Curator site, or the site itself
is rendering an error that says "failed to cache..." or "permission denied...", or "no such file found...",
use the following steps to resolve this issue:

1. Click the "clear cache" button on the backend of Curator
2. Use our [Filesystem Permissions Guide](https://docs.curator.interworks.com/server_management/system_administration/filesystem_permissions.md)
   to fix any errant file permissions settings.

## Fix Corrupted Files

If Curator is displaying an error message stating "vendor files are missing" or some pages may throw a
warning message that some files were not able to be found, you can re-download the Curator system files to
your web server using the steps below:

***Fixing Corrupted File Systems on Linux:***

1. `cd` into your webroot directory (e.g. `/var/www/html`)
2. Run the commands below, replacing the `[curator_key]` in the URL with your Curator license key. If you
   don't know your license key, reach out to your account manager for more information.

   wget -O latest.zip "[https://api.curator.interworks.com/get\_version.php?key=\[curator\_key\]\&kernel=473\&version=latest](https://api.curator.interworks.com/get_version.php?key=\[curator_key]\&kernel=473\&version=latest)";
   unzip latest.zip;
   rm -Rf plugins/interworks;
   rm -Rf vendor;
   cp core/. . -Rf

   NOTE: You may replace `latest` in the URL above with a specific version
3. Manually rerun database migrations using the steps provided in the **Updating Curator Database** section.
4. Visit your Curator site in a web browser to confirm whether your site is back up and running.

***Fixing Corrupted File Systems on Windows:***

1. From a web-browser visit the URL below to download a .zip file with your Curator filesystem, replacing the
   `[curator_key]` in the URL with your Curator license key. If you don't know your license key, reach out to
   your account manager for more information.
   `https://api.curator.interworks.com/get_version.php?key=[curator_key]&kernel=473&version=latest`
2. Make a backup of your webroot in case of any errors that occur in the steps below.
3. Unzip the file that was downloaded from **Step 1** into your webroot (e.g. `C:\InterWorks\Curator\htdocs`)
   and replace all files with the newly extracted files.
4. Manually rerun database migrations using the steps provided in the **Updating Curator Database** section.
5. Visit your Curator site in a web browser to confirm whether your site is back up and running.

## Event Log Troubleshooting

***Event Log Retrieval if You Can Access the Curator Backend in a Web Browser:***

1. Login to the backend of your Curator instance (e.g. `http://curatorexample.com/backend`).
2. Navigate to the **Settings** > **Logs** > **Event Log** section using the left-hand menu.
3. Look for any "upgrade" related errors.
4. Reach out to support for further troubleshooting.

***Event Log Retrieval if You Cannot Access the Curator Backend in a Web Browser:***

1. Log on to the web server that hosts Curator.
2. Find the Curator event logs:
   * **Windows**: `C:\InterWorks\Curator\htdocs\storage\logs`
   * **Linux**: `/var/www/html/htdocs/storage/logs`
3. Find the log file with today's date (e.g. system-2025-03-17.log ).
4. Copy the file and send it to Curator support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.