# Troubleshooting

If you attempted the upgrade and receive the message that your upgrade is **Partially Complete**, find the un-upgraded data sources by navigating to the **Upgrade Manager** and clicking the number in the **Available** column for the relevant connection.

Use the options below to resolve those un-upgraded data sources in order to finish your upgrade. See the linked how-to guides for more details on the actions to take.

*Note that these un-upgraded data sources still exist and are still protected by policy.*

1. [**Delete the remaining data sources**](#delete-the-data-sources): The easiest solution is to delete the data sources that did not upgrade. Note that disabled data sources that no longer exist in your data platform will never be upgraded. Only do this if you no longer need these data sources in Immuta.
2. **Adjust the privileges of the system user used to connect Immuta and your data platform**: Ensure that the Immuta system user can also access all remaining un-upgraded data sources in your data platform.
   1. **Expand privileges in** [**Snowflake**](#expand-privileges-in-snowflake)**,** [**Databricks**](#expand-privileges-in-databricks-unity-catalog)**, or Trino** (recommended): Extend the Immuta system user's privileges in your data platform by granting it access to all remaining un-upgraded data sources.
   2. [**Change the system user credentials used by Immuta**](#change-the-system-user-credentials-used-by-immuta): You can also provide Immuta with a different set of credentials that already have the required privileges on the un-upgraded data sources.

### Required Databricks Unity Catalog privileges

Ensure the Databricks service principal you created and connected with Immuta has the [required privileges to register a Databricks Unity Catalog connection](https://documentation.immuta.com/saas/configuration/databricks/databricks-unity-catalog/how-to-guides/connect-unity-catalog#create-the-databricks-service-principal).

### Required Snowflake privileges

Ensure that [the role you specified in the upgrade](#user-content-fn-1)[^1] has the [required privileges to register a Snowflake connection](https://documentation.immuta.com/saas/configuration/snowflake/how-to-guides/connect-snowflake#set-up-the-immuta-system-account) and has been granted to the [Immuta system user](#user-content-fn-2)[^2].

### Required Trino privileges

Ensure the user's credentials you provided have the [required privileges to register a Trino connection](https://documentation.immuta.com/saas/configuration/starburst-trino/how-to-guides/register-a-trino-connection#create-the-system-account-user).

## Delete the data sources

{% hint style="warning" %}
[Schema monitoring must be turned off in the schema project](https://documentation.immuta.com/saas/configuration/integrations/data-and-integrations/registering-metadata/schema-monitoring/how-to-guides/manage-schema-monitoring) to disable and delete data sources that did not upgrade.
{% endhint %}

{% stepper %}
{% step %}
**View the data sources that were not upgraded**

Find the un-upgraded data sources by navigating to the **Upgrade Manager** and clicking the number in the **Available** column.
{% endstep %}

{% step %}
**Disable the data sources**

From this data source list page, disable all the data sources to delete.

1. Check the top checkbox in the data source list table. Deselect the checkbox for any data sources you do not want to delete.
2. Click **More Actions**.
3. Click **Disable** and then **Confirm**.
   {% endstep %}

{% step %}
**Delete the data sources**

From this data source list page, delete the data sources.

1. Check the top checkbox in the data source list table. Deselect the checkbox for any data sources you do not want to delete.
2. Click **More Actions**.
3. Click **Disable** and then **Confirm**.
   {% endstep %}

{% step %}
**Finalize the upgrade**

Once the un-upgraded data sources are deleted, you should be able to complete the upgrade.

1. Navigate to the **Upgrade Manager**.
2. Click **Finalize**.
   {% endstep %}
   {% endstepper %}

## Expand privileges in Snowflake

{% stepper %}
{% step %}
**Check your role privileges**

To find the role you specified, do the following in the Immuta UI:

1. Navigate to **Connections**.
2. Select the connection you are trying to upgrade.
3. Navigate to the **Connections** tab.
4. See the **Role**.

Now, ensure that role has the [required privileges](https://documentation.immuta.com/saas/configuration/snowflake/how-to-guides/connect-snowflake#set-up-the-immuta-system-account) for each data source that was not successfully upgraded. Add the privileges where needed.
{% endstep %}

{% step %}
**Grant your role to the system account**

To find the system account you specified, do the following in the Immuta UI:

1. Navigate to **Connections**.
2. Select the connection you are trying to upgrade.
3. Navigate to the **Connections** tab.
4. See the **Setup**: **Username**.

Now, in Snowflake, grant the role to the system account:

```sql
GRANT ROLE <name> TO USER <user_name>;
```

{% endstep %}

{% step %}
**Run object sync**

1. Navigate to **Connections**.
2. Click on the **more actions** menu for the connection you are trying to upgrade.
3. Select **Run Object Sync**.
4. Click the checkbox to **Also scan all disabled data objects**.
5. Click **Run Object Sync**.

Now, navigate back to the **Upgrade Manager** tab, and if all your data sources are successfully upgraded, finalize the upgrade.
{% endstep %}

{% step %}
**Finalize the upgrade**

Once the un-upgraded data sources are resolved, you can complete the upgrade.

1. Navigate to the **Upgrade Manager**.
2. Click **Finalize**.
   {% endstep %}
   {% endstepper %}

## Expand privileges in Databricks Unity Catalog

{% stepper %}
{% step %}
**Check your service principal privileges**

To find the service principal you specified, do the following in the Immuta UI:

1. Navigate to **Connections**.
2. Select the connection you are trying to upgrade.
3. Navigate to the **Connections** tab.

Now, ensure that service principal has the [required privileges](https://documentation.immuta.com/saas/configuration/databricks/databricks-unity-catalog/how-to-guides/connect-unity-catalog#create-the-databricks-service-principal) for each data source that was not successfully upgraded. Add the privileges where needed.
{% endstep %}

{% step %}
**Run object sync**

1. Navigate to **Connections**.
2. Click on the **more actions** menu for the connection you are trying to upgrade.
3. Select **Run Object Sync**.
4. Click the checkbox to **Also scan all disabled data objects**.
5. Click **Run Object Sync**.

Now, navigate back to the **Upgrade Manager** tab, and if all your data sources are successfully upgraded, finalize the upgrade.
{% endstep %}

{% step %}
**Finalize the upgrade**

Once the un-upgraded data sources are resolved, you can complete the upgrade.

1. Navigate to the **Upgrade Manager**.
2. Click **Finalize**.
   {% endstep %}
   {% endstepper %}

## Expand privileges in Trino

{% stepper %}
{% step %}
**Check your system account privileges**

To find the system account you specified, do the following in the Immuta UI:

1. Navigate to **Connections**.
2. Select the connection you are trying to upgrade.
3. Navigate to the **Connections** tab.

Now, ensure that system account has the [required privileges](https://documentation.immuta.com/saas/configuration/starburst-trino/how-to-guides/register-a-trino-connection#create-the-system-account-user) for each data source that was not successfully upgraded. Add the privileges where needed.
{% endstep %}

{% step %}
**Run object sync**

1. Navigate to **Connections**.
2. Click on the **more actions** menu for the connection you are trying to upgrade.
3. Select **Run Object Sync**.
4. Click the checkbox to **Also scan all disabled data objects**.
5. Click **Run Object Sync**.

Now, navigate back to the **Upgrade Manager** tab, and if all your data sources are successfully upgraded, finalize the upgrade.
{% endstep %}

{% step %}
**Finalize the upgrade**

Once the un-upgraded data sources are resolved, you can complete the upgrade.

1. Navigate to the **Upgrade Manager**.
2. Click **Finalize**
   {% endstep %}
   {% endstepper %}

## Change the system user credentials used by Immuta

If you have another set of credentials on hand with wider privileges, you can edit the connection to use these credentials instead to resolve the un-upgraded data sources.

{% stepper %}
{% step %}
**Edit the connection**

1. Navigate to **Connections**.
2. Select the connection you are trying to upgrade.
3. Navigate to the **Connections** tab.
4. Click **Edit** and then **Next**
5. Enter the new credentials in the textbox and continue to the end to save.
   {% endstep %}

{% step %}
**Run object sync**

1. Navigate to **Connections**.
2. Click on the **more actions** menu for the connection you are trying to upgrade.
3. Select **Run Object Sync**.
4. Click the checkbox to **Also scan all disabled data objects**.
5. Click **Run Object Sync**.

Now, navigate back to the **Upgrade Manager** tab, and if all your data sources are successfully upgraded, finalize the upgrade.
{% endstep %}

{% step %}
**Finalize the upgrade**

Once the un-upgraded data sources are resolved, you can complete the upgrade.

1. Navigate to the **Upgrade Manager**.
2. Click **Finalize**.
   {% endstep %}
   {% endstepper %}

[^1]: This role can be found in the connection details tab of the connection.

[^2]: The username of this system user can be found in the connection details tab of the connection.