Troubleshoot Upgrades

Beginning with Fusion 3.1, upgrading Fusion uses a migrator that migrates objects and data from your current version of Fusion to a new version of Fusion or Fusion Server.

The Fusion migrator log file will help you troubleshoot difficulties while upgrading. If the migrator fails to complete successfully, we explain how to correct problems and repeat an upgrade.

Known issues, and workarounds if available, are listed at the bottom of this topic.

Log file

The log file for the migrator is in /opt/lucidworks/fusion/x.y.z/var/upgrade/tmp/migrator.log (on Unix) or C:\lucidworks\var\fusion\x.y.z\upgrade\tmp\migrator.log (on Windows). The x.y.z directory is for the Fusion version that you are migrating from.

Completing an upgrade after an error

If the migrator script produces an error, you will need to correct the problem that the script encountered, and then finish the upgrade as explained here.

1. Fix the error

If an upgrade step fails:

  1. Examine the log file and determine what went wrong.

  2. Fix what went wrong.

2. Repeat the step that failed

After you have fixed the source of the error, repeat the step that failed.

Note
You can repeat the step that failed as many times as needed to correct errors that occur. If the step continues to fail, restart the upgrade from the beginning.

3. Complete the upgrade

Complete the upgrade.

If a different step fails, fix that error, repeat that step, and then perform the remainder of the upgrade procedure.

If the upgrade steps produce no additional errors, then you are finished.

Restarting an upgrade

If an upgrade step continues to fail, then restart the upgrade process from the beginning:

  1. Examine the log file and determine what went wrong.

  2. Remove the directory for the new version of Fusion.

  3. Reinstall the new version of Fusion, but don’t start it.

  4. Fix what went wrong.

  5. Perform the entire upgrade procedure from the beginning.

Known issues

Following are known issues with the Fusion migrator.

Upgrades affected Issue Workaround (if available)

3.1.x to 4.0.y, 4.1.y, and 4.2.y

After migration, Query Workbench settings are reset for collections other than default

For collections other than default, print or write down all Query Workbench settings prior to upgrading. After the upgrade, redo the Query Workbench configurations by hand for collections other than default.

3.1.x to 4.0.y, 4.1.y, and 4.2.y

Users can’t log in after migration of a SAML realm

This is being investigated. No workaround is available at this time.

3.1.x to 4.0.y, 4.1.y, and 4.2.y

After migration, the query pipeline default (created during migration for the app default) is associated with collections in the Query Workbench, instead of the query pipelines that were associated with the collections before migration (typically <collection>-default).

In Query Workbench, for each collection with which the default query pipeline is associated, load the correct query pipeline, and then click Save.

3.1.x to 4.0.y, 4.1.y, and 4.2.y

Migration of index profiles and query profiles modifies the profiles. For more information, see Migration of index profiles and query profiles.

After migration, you might need to adjust the pipeline references of index profiles and query profiles by hand, and/or create new index profiles and query profiles.

3.1.x to 4.2.x

Migrated JDBC blobs are’t linked to apps.

Note
Apps function fine without these links. You only need to create links if you want the JDBC blobs to be visible under the "In Current App" tab in Object Explorer.

After migration, link JDBC blobs to apps manually, using either the Fusion UI or the Fusion API.

Fusion UI: (repeat for all apps, and all JDBC blobs in each app) In Object Explorer, locate a JDBC blob under "In Any App" or under "In No Apps". Hover over the object, click the App App icon, and then click Add to this app.

Fusion API:

  1. Find the blob IDs of JDBC blobs:

    curl -u admin:password "http://localhost:8764/api/apollo/blobs?resourceType=driver:jdbc"
  2. (Repeat for all JDBC blobs) To link a JDBC blob to all apps, use this API command:

curl -u admin:password -H "Content-Type:application/json"  -X PUT -d '{ "subject" : "group:_shared", "object" : "blob:JDBC_blob_ID", "linkType" : "hasPart", "originator" : "migration" }'  "http://localhost:8764/api/apollo/links"

All upgrades except for 3.1.x to 3.1.y

The managed-schema data in the Solr configuration can’t exceed 1 MB in size.

This is an example of a failure message:

2018-05-07T19:31:00,056 - ERROR
[main:ZKImportExportComponent@276]
- Error writing data to ZK
org.apache.zookeeper.
KeeperException$ConnectionLossException:
KeeperErrorCode = ConnectionLoss for
/lwfusion/3.1.5/solr/configs/rh/managed-schema

Remove unneeded elements from the schema, and then restart the upgrade from the beginning.

3.1.x and 4.0.x to 4.1.y and 4.2.y

Migrated signal-aggregation jobs retain their schedules (by design). To avoid job timeouts, the default schedule for signal-aggregation jobs was increased from every two minutes to every 15 minutes in Fusion 4.1.0.

After migration, consider manually changing the schedule of signal-aggregation jobs to 15 minutes.