Server Upgrade Best Practices
Although upgrading from one version of Alteryx Server to another is a straightforward process, there are several considerations and preparation steps that can help ensure a smooth upgrade. This page provides a topical overview of the process, including links to useful documentation, and a step-by-step approach to consider when planning your upgrade.
Not every step or recommendation in this document is applicable to every environment or installation. Your plan might differ.
In general, the upgrade process should consist of the following high-level steps:
The following sections describe these steps and add narrative to help plan your work. Links to detailed instructions, where they exist, will be shown inline, and an aggregated list of all the links provided in this document can be found in the Guides and Help Articles section.
Find a checklist of these steps in the Server Upgrade Checklist.
Alteryx and its partners are available to assist in planning and executing an upgrade. Speak to your Account Executive if you need assistance with this process.
New Terminology
With the release of Server 2022.3, the term Gallery has been deprecated in favor of Server UI. Although the legacy term still exists in the software and documentation at the time of this writing, this document uses Server UI to refer to the applicable services, nodes, configurations, and others.
Section 1. Document Your Environment
Capture Your Architecture and Configuration
It is necessary to have complete understanding (and documentation) of your environment. At a minimum, you need to know:
How many servers are installed, and what are their functions?
How many each of Controllers, Server UI instances, Workers, MongoDB and SQL nodes do you have in each of your environments (Dev/Test/Production)?
Do you run a High Availability (HA) Environment?
Is there an architectural diagram which visualizes the environment? If not, this is a good opportunity to create one.
What software version of Alteryx Server is running in your environment?
What additional software has been installed?
Custom R libraries
Custom Python libraries
Third-party utilities
Connectors
Not every connector needs to be upgraded, and some might not have an upgrade available.
Data packs: Location Insights, Business Insights, Intelligence Suite, and so on.
Best practice is to install matching versions of these add-ons during the upgrade, if available.
Custom tools designed by your users or downloaded from Community, other purchased or free third-party tools and connectors. Make a list of these, along with versions.
The configuration options which have been set via the Alteryx System Settings configuration tool, including but not limited to:
Workspaces
Logging Directories
Scheduler and Engine enablement settings
Persistence settings, including:
Database type
Data folder
Retention options
Server UI settings (URLs and security)
Authentication methods and IDP information
SMTP
Run-as User
Note
These configuration options (such as Scheduler, Engine, Persistence, Server UI, SMTP settings, Run-as User, and more) are captured in C:\ProgramData\Alteryx\RuntimeSettings.xml, so an admin doesn’t need to separately record settings. A copy of RuntimeSettings.xml provides all of these in a plain text XML file.
Service Log-On User
Physical and virtual server specifications
Cores and memory
OS version
For more information, go to Server System Requirements.
Databases and Python versions:
User-managed MongoDB: User-managed MongoDB version is independent of a Server upgrade. You might need to separately upgrade your User-managed MongoDB in parallel to a Server upgrade. In the case of the user-managed instance, Alteryx doesn't provide support. For more information, go to Version Support Policy.
Embedded MongoDB: Embedded Mongo and Python versions follow from the Server version and don’t need to be separately noted. For more information about embedded MongoDB versions, go to MongoDB Schema Reference or Version Support Policy.
User-managed SQL DB: User-managed SQL DB version is independent of a Server upgrade. You might need to separately upgrade your User-managed SQL DB in parallel to a Server upgrade. In the case of the user-managed instance, Alteryx doesn't provide support. For more information, go to Version Support Policy.
Note
If you are using the Python tool, please check the Python Tool Environment in Server Upgrades before upgrade.
Note
Your list of scheduled jobs, collections, workflows, and memberships is part of the MongoDB and is not lost during the upgrade.
We have prepared a Configuration and Architecture Checklist to make this step easier for you. Completing this checklist will give you an overview of your infrastructure and configuration.
Identify Business Critical Workflows
An important part of planning your upgrade is to identify business critical workflows that you want to protect and test as part of the upgrade process. These are generally workflows that are run on a schedule, act as dependencies to downstream work (inside or outside of Alteryx), and/or provide critical data/output to key stakeholders in the company. Essentially, you want to identify any workflow which, if unavailable for any significant amount of time, will have a deleterious effect on your business.
Identifying critical workflows can help you choose your target version. If the critical workflow contains tools or connectors that are not compatible with a particular version, you’ll want to take that into consideration when selecting your target version (see Section 3 below for the Version-to-Version Server Upgrade Guide: Supported Versions). These workflows can also be modified for post-upgrade testing (below) and included in your QA plan.
Create Test Versions of Business-Critical Workflows
When you test critical flows during your post-upgrade quality control, you’ll need to disable or edit any outputs that write data to other production systems, or produce outputs that will reside in the production environment.
A common methodology here is to create dedicated test versions of these flows which still access the target systems and directories, but will not overwrite data in production files and tables.
For data operations, change the outputs to write to dedicated test versions of tables.
For file operations, write files with a different file naming convention, or to a testing subfolder.
This allows you to do end-to-end testing that does not impact production. These test workflows should be used in production testing for the same reason.
Additional Considerations
Plan and schedule your upgrade activities to minimize disruption to your organization’s ongoing operations. Schedule the upgrade window outside of normal business hours (if possible), and during periods of "lighter" utilization. For example, do not schedule during fiscal year-end close, quarter-end processing, monthly audits, and so on.
Some clients use an upgrade window to revisit Operating System (OS) versions on their Alteryx machines. Please work with your IT Department if this is something you wish to do and review the System Requirements. Be sure to document in your upgrade plan whether you are upgrading the OS at the same time. If problems occur after the Alteryx upgrade, support engineers will be made aware of them.
Section 2. Perform a Server Health Check (Optional)
An Alteryx Server Health Check is a valuable resource for understanding usage patterns of an Alteryx Server environment. It analyzes historical usage patterns to determine how busy the Server environment is, what kind of optimization activities might be needed, and whether the environment is sized appropriately.
If you’d like to learn more, contact your Alteryx Account Executive.
Section 3. Select a Target Version or Versions
Choose the Server version you plan to upgrade to. Depending on your organization’s upgrade cycle, you may be several versions behind the latest release. The number of versions between your current and target version affects your upgrade approach, so plan accordingly.
Many organizations don’t upgrade with every release, especially since multiple versions can be released each year. However, staying reasonably current is important. Regular upgrades provide critical security updates, performance improvements, and new features.
A common strategy is to standardize on the latest release or the previous one to balance stability with timely access to enhancements.
Note
All major releases are supported for 24 months. If your organization has adopted infrequent updates, this should be critical to your decision.
Review the Release Notes
The first step in the selection process is to read the Release Notes. These detail new features and programming changes in the potential target versions, and detail bug fixes and known issues.
Understand the Upgrade Path - Where You Are Now to Where You Want to Go
Some releases have additional considerations if coming from certain prior versions, and some versions are not appropriate for all customers. For example, you might be required to upgrade your MongoDB in order to traverse between versions, or in the case of version 2022.3, you will need to upgrade Server and Designer together because of data encryption enhancements in the software that make that version of Server incompatible with prior versions.
The Alteryx Help & Support site has a Version-to-Version Server Upgrade Guide: Supported Versions (for unsupported versions, go to Version-to-Version Server Upgrade Guide: Unsupported Versions), which highlights tasks and considerations you need to be aware of when upgrading through versions of Alteryx Server. The guide is especially helpful if you are upgrading through multiple versions at once, such as migrating from 2019.1 to 2022.1. To ensure a smooth upgrade, you might need to take some incremental steps.
Select Your Version
Now that you have educated yourself on the various available versions and the special considerations that line your upgrade path, you are ready to select your target version. From here, proceed to the Downloads site.
Section 4. Download the Software
Visit the Alteryx Licensing portal. You need an account to visit the site. Once there, you’ll find all the downloads available to you, including but not limited to:
Alteryx Server (current and previous versions)
Alteryx Designer
Alteryx Intelligence Suite and Insights Data
Alteryx supported Database Drivers
Download all the software you need and continue to the next step in the process. For help downloading, visit the Download and Install a Product help page.
Version Parity
In general, it is best practice to keep Server and Designer on the same version. So, downloading the matching Designer installer at this time makes the most sense. However, since upgrading Designer across a large user base requires additional planning and resources, you might not wish to complete the upgrade at the same time as the Server upgrade.
As of version 2025.2, Alteryx has decoupled Designer and Server updates to modernize the update experience and reduce IT overhead. You can now upgrade Designer independently of Server.
Server is generally backwards compatible with older versions of Designer, with the caveat that new features supported on the target version of Server won’t be available in older versions of Designer.
In the case of Server and Designer 2022.3, this backward compatibility does not exist due to data encryption enhancements across the platform. If you are planning to upgrade to or beyond this version, Designer must be updated at the same time. There are special instructions found on the Migration Prep Tool help page for preparing an upgrade to this version. If you are trying to download an older version no longer available on the Downloads page, please contact Fulfillment.
Section 5. Perform a Sandbox Upgrade or Blue-Green Deployment
Warning
Directly upgrading your Production Server can lead to downtime if issues occur during the upgrade or during post-upgrade testing.
If a backup is not available, you might be unable to roll back, leaving your Production environment down until the upgrade issue is resolved.
Better practices include...
Sandbox Upgrade
Testing the upgrade in a non-production environment and documenting your process steps before upgrading your production Server helps ensure a smooth upgrade. This also helps confirm that business-critical workflows and third-party tools continue to run as expected. In the event they do not, it provides an opportunity to explore and remediate these issues and add these remediation steps to your production upgrade plan. The steps you follow in this test upgrade, plus any additional remediation steps you add in the quality control phase, will become your upgrade “script” for production. Contact your Account Team to request a Sandbox license.
Blue-Green Deployment
A Sandbox server upgrade becomes the new Production environment after validation. This eliminates the risk of your Production Server being down for an indeterminate amount of time as it is not upgraded in place. The original Production environment is blue, and the new/Sandbox environment is green, where updates can be deployed and tested. Blue-Green deployment validates that the Server environment and required database drivers, DSNs, Connectors, and other settings are fully understood as they must be set up on the Sandbox for validation.
The table below shows a tiered list of minimum to best-case recommendations when upgrading Server:
Embedded Mongo Backup | Minimum | Better | Best | Benefit |
|---|---|---|---|---|
Backup MongoDB | ☑ | ☐ | ☐ | Preserves database information for rollback in the event of errors during the upgrade. Rollback may include manual steps and may require the assistance of Alteryx Support. |
IT Snapshot of the Windows Server Machine | ☐ | ☑ | ☐ | Provides quick and easy rollback with no manual steps. Steps: Your IT team will back up a complete instance of the Alteryx Server machine. Note: The Service must be stopped so the Snapshot doesn’t capture the database while it’s being updated. This could leave it in a non-functional state when restored. |
Blue-Green Deployment | ☐ | ☐ | ☑ | A database backup is needed in a Blue-Green Deployment to migrate host machines, but an IT snapshot is not necessary. |
User-Managed Mongo or SQL Server Backup | Minimum | Better | Best | Benefit |
Back Up the Database | ☐ | ☐ | ☑ | Upgrades perform schema migrations on database collections. The original database is required to be able to roll back the upgrade. |
Upgrade | Minimum | Better | Best | Benefit |
In-place Upgrade of Production Server | ☑ | ☐ | ☐ | Easiest to perform, but highest risk of unpredictable Production Server downtime in the event of an upgrade issue. |
Test Upgrade on a Sandbox Server | ☐ | ☑ | ☐ | Flush out upgrade issues and test critical workflows and Connectors in the upgraded environment without Production downtime. Steps: Perform a Host Recovery to a Sandbox environment:
After validation of upgrade process, perform an in-place upgrade of Production Server. |
Blue-Green Deployment | ☐ | ☐ | ☑ | Blue-Green deployment eliminates risk and potential downtime of an in-place upgrade as the original Production environment is not upgraded. Steps: Perform a Sandbox upgrade, validate critical workflows, then switch the URL of your Production environment to the Sandbox (making it the new Production environment). |
Ideally, start with the same-version Sandbox/Dev/Test Server and upgrade it. See the Alteryx Server Sandbox Environment Community article for more information on Sandbox environments.
If you have a multi-node environment, testing is still effective on a single machine that runs Controller + Server UI + Worker. Similarly, if you have a User-Managed MongoDB, restoring a database backup to the test machine's embedded MongoDB can help validate the upgrade. Contact your Account Executive for information on a Sandbox license.
At a bare minimum, you should install the target version of Designer on a user's machine to test critical workflows in the new version. Instructions can be found on the Install Two Versions of Designer on the Same Machine help page.
1. Perform a Backup
Perform a backup for:
User-Managed MongoDB and SQL DB
Note that creating a backup is the responsibility of the customer and is not supported by Alteryx.
2. Complete Pre-Upgrade Checks
You can avoid many Server upgrade problems by performing the pre-upgrade checks/workflow found in the Alteryx Server: Pre-Upgrade Checks Community article. This procedure addresses the most common issues a client will face performing an upgrade and lists the recommended solutions/steps for each.
It’s important to run the pre-upgrade checks in each of your environments before performing the upgrade. For example, you are testing on a development machine, then you’ll want to rerun the checks on your prod environment and take the indicated steps before completing that upgrade.
As part of pre-upgrade planning, agree with business stakeholders on how long the upgrade will be allowed to run before triggering a rollback.
For best results, avoid combining a Server upgrade with a host migration. Perform one operation at a time, allowing for a full validation period after completion before starting the next.
Disable Scheduler on Worker Nodes During Upgrades
By default, schedules that should have run while the Server was being upgraded will pick up as soon as the Server and nodes restart. Keep this in mind when running the test upgrade on your Sandbox, as you likely don’t want to have workflows kick off and impact your production systems.
We recommend to disable all schedules prior to upgrade and determine what should run on an individual basis.
If you do not want schedules to run when the Service starts:
Run Alteryx System Settings on each Worker (and main Server node).
Deselect Worker > General > Run unassigned jobs.
Give the Worker a unique Job tag (for instance “UPGRADETESTING”).
Alternatively, contact Customer Support for assistance in deleting all schedules.
3. Perform the Upgrade
Performing the upgrade is a straightforward process if you are upgrading in place. There are different steps if you are performing a fresh installation of the new version on a target machine, which include the application of licenses which is not part of the upgrade path; existing active licenses continue to work on upgraded machines without intervention. The general upgrade steps are shown on the Install or Upgrade Server.
The different instructions for new installations and upgrades-in-place are detailed, and the document includes links to associated help files/articles on licensing, system requirements, preparatory checklists, MongoDB upgrades, and more. Many of these are included in the Guides and Help Articles section at the end of this document.
Please note that Predictive Tools should be upgraded with the main installation. If you had a Service Log-On User set, you need to set it again after the upgrade; upgrades remove and reinstall the Alteryx Service.
Upgrading a Multi-Node Environment
In multi-node environments, all nodes should be upgraded to the same version and nodes must be shut down in the order shown in the Shutdown section of the document in the How to Restart the Services in a Multi-Node Alteryx Server Community article.
After you upgrade all nodes, follow the proper restart order listed in the Startup section of the same document.
Once everything is up and running, upgrade any connectors, data packs, drivers, add-ons (such as Intelligence Suite), and third-party tools that need to be.
4. Test the Upgrade
Now that the Server software and any applicable connectors have been upgraded, it is time to start testing.
Alteryx Services
The first tests are basic and you can find them in the Test section of the Server Upgrade Checklist.
Is the Alteryx Service running?
Can you:
Access the Server URL?
Move around Admin pages and view Users, Collections, and so on?
Publish a workflow from Designer to the Server?
Run the workflow?
If your configuration allows, save and run a workflow specifying your credentials?
Configuration Options
Next, examine the configuration options in the Alteryx System Settings configuration tool to ensure that no settings have been lost. These settings were documented in the Document Your Environment section. If there are any changes you need to make, such as persistence settings, SMTP configurations, etc., now is a time to make them. Also, make a note of these changes to reuse them in your upgraded production environment.
Note
Some settings are actively changed across some of the upgrades. For example, 2022.1 set AMP on for the Server and changed the number of workflows allowed to run simultaneously.
Always check the Release Notes for more information.
Connectors and Drivers
The next step is to test your connectors and drivers to critical systems, such as SharePoint and O365 connectors, and ODBC/OleDB connectors to SQL Server, Snowflake, Databricks, and so on. Make sure you can connect, read, and write data.
Critical Workflows
Now, test your business-critical flows and flows that utilize the connectors also documented in the Document Your Environment section. This set of tests will use the test versions of the workflows created in the Create Test Versions of Business-Critical Workflows section of this guide. If you run unmodified productions versions of these flows, then your production destinations will be impacted as if these flows were running normally.
Scheduler and Server UI
Finally, if you are running Scheduler and Server UI, test these as well:
Can a workflow be scheduled, and does it run?
Do analytic apps run correctly?
Important
Make sure that any apps you publish and schedule/run in this environment are not production versions. If you run unmodified productions versions of these flows, then your production destinations will be impacted as if these flows were running normally.
5. Note Any Errors and Get Help
Catalog any problems your testing uncovers, such as:
Services that don’t start or report errors.
MongoDB Schema or crypto migrations that fail.
Workflows that don’t run or run with unexpected results or errors.
Connectors that don’t work.
Errors in MongoDB.
The Server Upgrade Checklist includes some common troubleshooting steps in the last section. Customer Support can assist if you experienced an error in the upgrade process and are unable to resolve it with the common troubleshooting steps shown in the guide. Your Account Executive can provide options if you would like assistance planning or executing an upgrade.
6. Perform a Rollback/Restore
If you were unable to resolve issues that were uncovered during the Test and Quality Control phase, it’s time to do a rollback or restore. Prior to rolling back or restoring, you might wish to gather log files from the Server machines to provide to Customer Support or for internal review prior to the next upgrade attempt. If you have a snapshot/backup, you can revert to it now, and plan your next upgrade attempt. If a snapshot methodology was not possible, then you can follow the conventional rollback methodology shown in the How To: Downgrade Alteryx Server Community article.
Section 6. Schedule the Production Upgrade
Once you have successfully tested the upgrade in your non-production environment, and have your documented upgrade process, it is time to plan your production environment upgrade.
Note
Your production upgrade should follow the “script” you created in your test environment, with changes specific to any architectural differences between the environments. For example, if your tested environment was a single node architecture, but your production environment has separate nodes for Workers and Server UI, then the production environment will have additional installation steps. Be aware of this as you plan.
Pro tip: Use Server Notifications via Alteryx Server UI as an additional communication channel to inform users about pending upgrades. You can also post upgrade information in your internal Alteryx community (for example, SharePoint, Confluence, Yammer, Teams, and so on).
You’ll need to schedule an appropriate amount of downtime and inform the users that workflows on Server will not be running during the upgrade. For business-critical flows, users can run them in your newly upgraded test environment, run them locally, or simply plan for the outage and inform affected downstream audiences about the delay.
If you are planning to upgrade Designer as well, whether via packaging/automation methods or manual installation process, plan for the extra time and resources needed to complete the installations, and be sure to inform your user base as well. Remember that Server is backward-compatible with Designer, up until version 2022.3, but newer versions of Designer do not work with older versions of Server. So, Server upgrades must always precede Designer upgrades.
Important
Remember to plan your upgrade at a time that minimizes disruptions to your business. Refer to Additional Considerations for more detail and recommendations.
Section 7. Perform the Production Upgrade
Upgrade Server
The high level steps in this section are a mirror to steps 1-6 in Section 5. Refer to the appropriate section for additional details and help links.
Perform the upgrade, including connectors, data packs, add-ons, third-party tools, etc.
Test/Quality Control the upgrade.
Check that scheduled jobs, collections, memberships, and published workflows still exist and work as expected (where testable).
Perform a rollback/restore if necessary.
Restore from backups or follow the process in the How to: Downgrade Alteryx Server Community article.
Upgrade Designer (optional)
Once your production environment is up and running, you can upgrade your Designer installs if they are part of your plan. Remember that Designer cannot be a greater version than what has been installed on Server, and this upgrade affects users’ machines directly. Steps for upgrading Designer can be found in Upgrade Designer.
Designer and Server Compatibility
Designer version needs to be equal to or older than the Server version it connects to. The exception is Server 2022.3 (or later) which requires at least Designer 2022.3 due to changes in encryption.
Designer version can NOT be newer than the Server it connects to.
Only the version (Year.Release) needs to match, not the specific patch.
Similar to a Server upgrade, upgraded Designer versions should be tested to ensure that workflows continue to run, and that connections to Server can still be made. As with the best practices for Server upgrades, plan to test your Designer upgrade on a small subset of user machines.
What to Do if the Upgrade Fails
If the Server upgrade fails or encounters critical issues, do not repeatedly restart the upgrade process. Instead, follow the steps below to collect diagnostic information and engage Alteryx Customer Support for assistance.
1. Submit a Support Ticket
Open a case with Alteryx Customer Support and include the following details:
The Server version you upgraded from and to.
A brief description of what failed (for example, during installation, after service start, or during schema migration).
Environment type: Is this a single-node or multi-node configuration?
Was a host migration attempted at the same time as the upgrade?
Is this a production server environment?
The timestamp of failure and any visible error messages.
Have any troubleshooting steps already been taken? (for example, service restart, system reboot, or manual rollback attempt)
Do you have a current backup of your Alteryx Server and database data?
Include the log files listed below from the past 24 hours (or the 2–3 most recent log files) for troubleshooting:
Server (Gallery) Logs
Location:
\%ProgramData%\Alteryx\Gallery\LogsService Logs
Location:
\%ProgramData%\Alteryx\Service\AlteryxServiceLog.logInclude multiple
.logfiles if available.RuntimeSettings.xml
Location:
\%ProgramData%\Alteryx\RuntimeSettings.xmlAlteryxGallery schema migration log configured in Alteryx System Settings > Server UI > Logging Directory.
Versions 2025.1 and later:
C:\ProgramData\Alteryx\Service\alteryx-gallery-migration.csvVersions 2024.2 and earlier:
C:\ProgramData\Alteryx\Gallery\Logs\alteryx-migration.csv
AlteryxService schema migration log configured in Alteryx System Settings > Controller > Logging.
Versions 2025.1 and later:
C:\ProgramData\Alteryx\Service\alteryx-service-migration.csvVersions 2024.2 and earlier:
C:\ProgramData\Alteryx\Service\alteryx-migration.csv
AlteryxServiceMigrator_#.logs (required when upgrading to or through version 2022.3), found in:
Prep Tool logs:
C:\ProgramData\Alteryx\ServiceService start logs: Alteryx System Settings > Controller > General > Logging folder
2. Additional Information (Optional)
If possible, also include:
Screenshots of any error messages.
Installer log files (typically in
%TEMP% or %LOCALAPPDATA%\Temp).Output from any Migration Prep Tool used before the upgrade.
3. Next Steps
Do not uninstall or roll back unless directed by Alteryx Support.
Wait for Support to analyze the logs and provide remediation guidance.
Guides and Help Articles
On this list you can find links to all resources mentioned in this document, as well as additional resources which can be helpful in the Server upgrade process.