Early bird tickets for Inspire 2023 are now available! Discounted pricing closes on January 31st. Save your spot!

Alteryx Connect Knowledge Base

Definitive answers from Connect experts.

Troubleshooting Metadata Loading in Connect

Alteryx Alumni (Retired)

Connect Banner.png

There are some common issues that may arise in the harvesting of metadata and it’s our hope that this guide will help you diagnose them with ease!

There are two general buckets of errors when harvesting metadata: errors that happen during loader execution, and errors that happen on the Alteryx Connect Server after metadata loader execution is complete.

Error in Loader Execution

In the event of an error with the loader execution, review the Designer error message and Tool ID. This should catch most authentication errors.


Common reasons for authentication errors include:

  • Account in Connect is not in the “Administrators” group
  • The Connect URL is not found by the referenced name. Check that the Alteryx Server can reach the Connect server
  • Specifically for the Alteryx Gallery loader, confirm you are using the Admin API Key and Secret
  • For source systems, confirm your account has access with the necessary permission level indicated by the metadata loader’s documentation

Beyond authentication errors, other errors may be reviewed within the workflow itself, using the Tool ID from the error message:


The error message, and previous job errors should also be captured in the Engine Logs (defined by Options > User Settings > Edit Users Settings > Engine Logs)

Other reasons for errors within loaders:

  • Missing metadata of an expected type (ex: “Views”)
    • Check the permission level for the source system account you’re executing with has the necessary permission level indicated by the documentation
  • Connect Tools “Connect JSON Builder” and “Connect Output” missing
    • Make sure the loader install has been installed on the machine. Re-run the install with version matching Connect
  • Metadata parsing errors

Error on Alteryx Connect Server

In the event of a problematic run without an error notification in Designer (such as metadata not being visible in the Connect site), try troubleshooting on the Connect server. From the Connect website, the administrator can view information helpful to understanding the metadata import and use. To begin, as an Administrator, review the recent entries in the master log:


Any problems loading data, reconciling data, or building indexes should be indicated here.


The “Stage” tab lists details for each metadata source. This allows you to compare the total records against the expectation. Removing a Stage with the trashcan icon on the right will remove a metadata source from the system, including breaking manually-generated relationships, and removing unique IDs for each metadata entity for that load code. Removing Stages is usually not necessary, but useful in reviewing how many entity records Connect received from the source system:



The status of metadata loading for each source type is listed in “Jobs”. Review the Loading Status:


In the event of certain process interruptions, a Job may not have completed successfully. If the loading status is not “Complete” or “In Progress” for your source, Select the source and “Synchronize”. This will attempt to reload records from Stage to Master tables and rebuild indexes.


If metadata is not appearing in Connect, and you’ve already synchronized the metadata load to completion, attempt a Re-Index. A full Re-Index is usually not necessary and can be slow with a lot of content, so you may choose to Re-Index just a portion of the content. To do so, simply select an Entity type and click “REINDEX”. You may select “APPS” (for example all tables from a database with “Database Server”) or specific ENTRIES (for example a specific table):


After Re-Indexing, review any missing content in Connect. If anything is still missing after Re-Index and Synchronize, refer to the master Catalina Log for additional troubleshooting.

Authentication Errors

Failure to log into Connect: “Alteryx Connect sign-in error. Wrong credentials or server error”

  • Confirm you’re using the Admin API Key and Secret, not the standard API
  • Confirm you’ve not modified the loader endpoint. Your URL should contain “/gallery/api/admin/v1” after your base Gallery URL
  • The base URL should match what’s defined in the Alteryx Server System Settings

Source System Authentication Errors

  • The loader message should indicate the source system threw the authentication error
  • If the error indicated restricted access to certain type of content on the source system (eg: “can’t read from ‘schemas’”), this could indicate your account lacks the required privileges (see below)

Improper Access Level to Execute Source System Queries

  • Certain permission levels are required to pull metadata from source systems
    • Review the metadata loader prerequisites specified in the help documentation linked above

Missing “ConnectTools.dll” in 18.1 or 18.2

  • Confirm version match between loader install and Alteryx Server
  • Uninstall Loaders via Windows’ “Add Remove Programs”, and reinstall loaders from the Connect downloads page
  • Manual fix in 18.2 by placing ConnectTools.dll into [InstallDrive]\Program Files\Alteryx\bin\Plugins\

Misconfigured Network Access

  • Confirm access to source system via browser, ping, or driver, depending on the source system.

Metadata Loading FAQ

What metadata is captured by the loader?It depends on the loader. For relational databases, this is typically columns, tables, views, procedures, schemas and catalogs. Reporting platforms like Tableau may contain other types of entities like data sources, workbooks, projects, users, and thumbnail.
Can the loaders parse SQL statements to determine joins and other relationships defined within a single View, SPROC, etc?No, we’re currently not doing any SQL parsing from views or SPROCs in sources systems. We do parse simple SQL statements within Alteryx Input Tools for simple Select statements.
Do the loaders pull usage information (like how many queries per day a SQL table receives)No, we don’t gather or display usage. We do track page views within Connect, but not from source systems.
Do the loaders push any data values to Connect?No. We do profile data in some cases, but only simple aggregations like count distinct. No data values get pushed to Connect.

Important Note!

In version 2021.3.6 and later, the Alteryx Gallery API has changed.  Please follow the examples in the data entry panel of the Loader:

This has changed as of 2021.3.6.This has changed as of 2021.3.6.