Troubleshooting and Upgrade/Migration
Troubleshooting follows the request path: user → Gallery → Controller → Worker → data source. Isolate which link fails. Common categories: authentication/permission (cannot log in, cannot run), connectivity (Worker offline, Controller unreachable, firewall/port), execution (workflow fails on Worker, missing macro/driver, credential error, path not found), resource (disk full, memory exhausted, queue backlog), and data (source unavailable, schema change). Logs (AlteryxService, Gallery, MongoDB, and the job's own results/log) narrow the cause quickly.
Upgrades: back up MongoDB and the persisted workflow directory first; follow the supported upgrade order (typically database and Controller considerations before Workers, per the release notes); verify the service account and permissions survive the upgrade; and re-test schedules, apps, and data connections afterward. Migration (new hardware or environment) means restoring both backups, re-pointing Workers to the new Controller, updating the Gallery base URL and SSL certificates, and re-validating authentication (especially SSO/SAML) and API keys.
Traps: upgrading without a backup of both stores; assuming an in-place upgrade preserves custom settings and drivers; forgetting to re-point Workers after a Controller move; and not re-testing SSO after a URL or certificate change.
Worked example: After migrating the Controller, all Workers show offline. The Workers still reference the old Controller hostname. Update each Worker's Controller setting in System Settings, restart AlteryxService, and confirm they register.
Rule of thumb: back up both stores, follow supported order, then re-test auth, schedules, and connections-most upgrade incidents are missed configuration, not data loss.