Alteryx Server Knowledge Base

Definitive answers from Server experts.

Alteryx Server: Pre-Upgrade Checks


Alteryx Server: Pre-Upgrade Checks

There are some major MongoDB changes starting in Alteryx Server version 2020.1. These database changes (also known as schema changes) are completed by a process referred to as a "schema migration". This schema migration is triggered the first time the AlteryxService restarts after the upgrade.

In order to help minimize the risk of errors during this schema migration process, we have provided an Alteryx application that will run checks on your Mongo database prior to upgrade.
The output of this application is a .pdf document with a summary of what changes (if any) must be made prior to the upgrade.

NOTE: This application is only intended to validate issues commonly faced during customer upgrades and may not cover every issue.  It does not guarantee that your upgrade will complete successfully.

This article will refer to specific collections and fields within the Mongo database. A full schema of MongoDB can be found here: MongoDB Schema Reference | Alteryx Help



  • Alteryx Server
    • Current Version 2018.3-2020.x. Upgrading to 2020.x+
  • Embedded MongoDB
    • The application will also connect to a User-Managed MongoDB replica set if you can identify the Master node.




  1. Download and run the Alteryx application attached to this article (.yxzp file).
    • Ideally, you will run this from the Controller machine that holds the database. If you are running it from a different machine, you must replace localhost (see Step 3) with the machine name of the Controller machine that holds the database. The machine you are running from must be able to communicate to the Controller.
      1. I.e.: localhost:27018 would be replaced with myservermachine:27018
  2. Gather Host and Password from Alteryx System Settings > Controller > Persistence section.


Configure and Run the Application



  1. Enter the Host value gathered from Step 3 above.
  2. Enter the Password value gathered from Step 3 above.
  3. Select the current version of Alteryx Server that you are running.
  4. Select which method of Authentication you are using on the Gallery.
    • If you are unsure, please check the Alteryx System Settings > Gallery > Authentication section.
  5. Select Finish to run the application.


How to Read the PDF Report Output

The output has the following sections:

  • Current Database Schema Version
  • Null/Incorrect Database Entries
  • Duplicate Users


Current Database Schema Version

This section will always contain data.

This section checks the current Schema version, as reported from the AlteryxGallery.versions collection. It will show:

  • The current Schema version in the database
  • The expected Server version that matches this schema version

Please check that this matches the expected "MongoDB Schema Version" for your current version of Alteryx Server found here: MongoDB Schema Reference . If it does not, please contact Alteryx Support , reference this article, and include the PDF Output.

Example Output


Null/Incorrect Database Entries

This section will only contain data if there are entries that need to be corrected prior to upgrade.

This section checks various collections in MongoDB that are known to contain values that can prevent the schema migration from completing successfully.

Please reference the below table for the various checks. If any of these fields are returned in your PDF report, please see the corresponding "Next steps" column.

Section Issue Next Steps
User values to update Users with null FirstName, LastName, Email, SubscriptionId or Curator fields See this article
Subscriptions to update Subscriptions with null ExpDate (Type 2) See this article
Collections to update (Windows Authentication only) Collections that contain users with incorrect SIDs Contact Alteryx Support
Users with mismatched SIDs (Windows Authentication only) Mismatched SIDs between AlteryxGallery.users and AlteryxGallery.windowsIdentitys Contact Alteryx Support


Example Output




Duplicate Users

This section will only contain data if there are entries that need to be corrected prior to upgrade.

This section checks the AlteryxGallery.users collection in MongoDB for users that have duplicate emails, for example:

FirstName LastName Email
Sally Jensen
Sandra Jensen

Please refer to this article (How to Fix Users with Duplicate Email Addresses ) for steps on how to correct these values, and reach out to Alteryx Support if you need additional assistance.

Known Issues


mongo_migration_pull_data_schema_agnostic (180)    USERS_MongoDB Input: Mongo Error (getCollectionNames) : { msg:"Authentication failed.: generic server error" code: Authentication failed.: generic server error } 

Check your database details are correct, and re-run.

AYX MongoDB Input Macro_WA (309): Record #1: WINIDENTITYS_MongoDB Input: Collection windowsIdentitys not found in database AlteryxGallery. AYX MongoDB Input Macro_WA (309): The output connection "WindowsIdentities" was not valid

You selected the wrong Gallery Authentication method. Confirm your Gallery Authentication method in the Alteryx System Settings > Gallery > Authentication section.

mongo_migration_pull_data_schema_agnostic (180)    COLLECTIONS_MongoDB Input: Mongo Error (getCollectionNames) : { msg:"No suitable servers found (`serverSelectionTryOnce` set): [connection refused calling ismaster on '']: generic server error" code: No suitable servers found (`serverSelectionTryOnce` set): [connection refused calling ismaster on '']: generic server error } 

If you are only getting an error on the COLLECTIONS_MongoDB Input tool, this means your Gallery contains no Collections. Please contact Alteryx Support , and reference this article.

Additional Resources

No ratings
8 - Asteroid

Hi, I've tried to run this on our user-managed mongo replica set and I get the below error:


ToolId #202: The field "LastLoginDate" is missing. Compare the tool configuration with the input stream.

I'm running this from Designer Version: 2021.2.2.45235.  The server version is 2021.2.  

I am supplying just the primary mongo node's address/port.  We also use SAML authentication.


@mse139 I'm sorry to see you are running into this issue. We are investigating. In the meantime, you can manually run the queries found on the linked articles:


Please use the link at the end of the article to contact Support if you need further assistance!