Troubleshooting Tableau connectivity
Symptom-first troubleshooting for Tableau connectivity - PAT failures, SSL certificate errors, host and site issues, Metadata API limits, mid-run 401s, and WAF blocks.
Resolve common Tableau connectivity issues when integrating Tableau with Atlan. Find the symptom you're seeing in the quick index - each entry includes a check you can run yourself before opening a ticket.
Quick index
| You see | Most likely cause | Jump to |
|---|---|---|
| 401 · "The personal access token you provided is invalid" (code 401001) | PAT expired, revoked - or a replacement PAT that silently failed to save | PAT failures |
CERTIFICATE_VERIFY_FAILED - "unable to get local issuer certificate" / "self-signed certificate in chain" | Incomplete or untrusted certificate chain | SSL certificates |
| "Unable to connect to tableau instance. Please verify server port…" / host, site, or connection errors | Wrong host, port, site name, or a https:// prefix | Host, port & site |
"Still creating the Metadata API Store", NODE_LIMIT_EXCEEDED, 30-second timeouts | Tableau Metadata API state or limits - not a network fault | Metadata API |
| Crawl starts fine, dies mid-run with 401 (code 401002) | Another session stole the shared PAT | Mid-run 401 |
| HTML block page in the logs ("The requested URL was rejected…") | WAF / proxy content rule | WAF blocks |
| "Server REST API Version check failed" in preflight | Usually not a version problem - see inside | PAT failures |
PAT failures - #1 issue by far
Symptom. Test Authentication or a scheduled workflow fails with:
Tableau signin failed (401): {"error":{"summary":"Signin Error",
"detail":"The personal access token you provided is invalid.","code":"401001"}}
Two other messages are usually this same problem wearing a mask:
- "App service returned an internal error" in the Test Authentication UI - check the workflow logs; a 401001 is often underneath.
- "Server REST API Version check failed" in preflight - the version check is simply the first call that needs a sign-in; an expired PAT fails it first. Teams have chased a "version problem" for weeks while the PAT had expired.
Why. In order of frequency:
- The PAT expired. Tableau kills PATs unused for 15 consecutive days, and all PATs have a maximum lifetime. Scheduled crawls that were paused, or tokens created and forgotten, hit this constantly.
- The replacement PAT never saved. A non-admin Atlan user pasted a fresh PAT, the UI appeared to accept it, but the connection kept the old token.
- The PAT's owner left the company and the account was disabled.
- Name mismatch. The PAT name is case-sensitive and must match exactly; stray whitespace counts.
Fix.
- Create a fresh PAT on the service account (name + secret).
- Have an Atlan admin (or Workflow Admin) update the connection credentials.
- Click Test Authentication after saving - a pass here proves the new token actually persisted.
- Re-run the workflow; set a calendar reminder for the token's expiry.
SSL certificate failures - #2, Tableau Server (and occasionally Cloud)
Symptom.
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify
failed: unable to get local issuer certificate (_ssl.c:1016)
-- or: certificate verify failed: self-signed certificate in certificate chain
Decode the message.
- "unable to get local issuer certificate" → your server presents an incomplete chain (leaf only, missing intermediates). Browsers often still work - they cache intermediates - so "it opens fine in Chrome" proves nothing.
- "self-signed certificate in certificate chain" → the chain ends at a private/self-signed root Atlan doesn't know. Paste the chain into the connection's SSL certificate field.
Check yourself (any machine that can reach the server):
openssl s_client -connect tableau.example-corp.com:443 -showcerts </dev/null | grep 's:\|i:'
Fix. Incomplete chain → add the intermediate(s) to Tableau Server's TSM SSL chain file. Private CA → paste the full PEM chain (leaf → intermediates → root) into Atlan's SSL certificate field (Server guide Phase 4). Recent cert rotation → update the pasted value; it doesn't follow rotations automatically.
Tableau Cloud uses publicly trusted certificates - the SSL certificate field should be empty for Cloud connections. A stale pasted certificate has caused intermittent Cloud failures; clear it and retest. Rarely, transient chain issues during Tableau's own certificate rotations self-resolve within hours.
Host, port & site errors
The exact strings the connector returns and what each means:
| Error text | Meaning / fix |
|---|---|
| "Unable to connect to the specified host. Please verify that the host details are correct and retry." | Hostname typo or DNS. Also triggered by pasting https:// into the host field - enter the bare hostname only. |
| "Unable to connect to tableau instance. Please verify server port or check if your server is up and running." | Wrong port, server down, or a firewall silently dropping the connection (see allowlists). On PrivateLink, also check the NLB rules and the pending acceptance (special cases). |
| "The site details provided are incorrect. Please provide correct site details." | Site name typo or wrong case - it's case-sensitive. Tableau Server default site → leave blank. |
| "Unable to connect. Please check your SSL setting." / "The ssl details provided are incorrect. Please provide correct ssl certs." | SSL toggle vs. server mismatch (HTTPS vs HTTP), or a malformed pasted certificate → SSL certificates. Enter the certificate in the recommended format. |
| "Provided username is incorrect. Please check." | Basic auth: confirm the username exists in Tableau, or add a new user. |
| "The client id provided is incorrect or site is empty or connected app in tableau is deleted." | JWT auth: verify the Connected App still exists, is enabled, and the site field is filled. |
| "The secret id provided is incorrect or the secret value is deleted." / "The secret value provided is incorrect." | JWT auth: verify the Connected App's secret ID and that the secret value hasn't been deleted. |
Metadata API errors - Tableau-side limits, not your network
These appear after a successful sign-in, during the lineage crawl:
| Error | What it is | What to do |
|---|---|---|
| "Still creating the Metadata API Store… BACKFILL-RUNNING" | Tableau is (re)indexing lineage - happens on first enablement and after quarterly Tableau upgrades; can take up to a week on large servers | Wait for backfill to finish (your Tableau admin can check status), then re-run |
NODE_LIMIT_EXCEEDED | A lineage query touched more than Tableau's default 20,000-node cap | Tableau Server admin can raise metadata.nodelimit (Tableau supports up to 100,000); or narrow project filters |
| "Execution cancelled because timeout of 30,000 milliseconds was reached" | Tableau's own internal 30-second GraphQL timeout on very large estates | Tableau-side tuning; run crawls off-peak; narrow scope. Not fixable from Atlan's side |
PERMISSIONS_MODE_SWITCHED ("…your results have been automatically filtered…") | Tableau filtered query results due to sensitive-data permission rules | Review the crawl user's permissions/site role; if the workflow hangs or loops on this, escalate to Atlan support |
See also Tableau's own common Metadata API errors.
Crawl dies mid-run with 401
Symptom. Sign-in succeeded, the crawl ran for a while, then:
{"error":{"summary":"Unauthorized Access",
"detail":"Invalid authentication credentials were provided.","code":"401002"}}
Why. A PAT supports one active session at a time. Another workflow, script, or person signed in with the same PAT mid-crawl, which terminated your workflow's session.
Fix. One dedicated PAT per Atlan connection/workflow; stagger schedules so they don't overlap. Audit where else that PAT is used. See Personal access token authentication.
WAF blocks - allowlisted IP, blocked request
Symptom. The workflow log contains an HTML page instead of JSON, e.g. "The requested URL was rejected. Please consult with your administrator. Your support ID is: …" - typically on the lineage (GraphQL) calls, while sign-in works.
Why. A web application firewall in front of Tableau Server matched a content rule against Atlan's GraphQL POSTs. This can start suddenly when either side updates (new WAF rules, or a connector update changing the request signature).
Fix. Give your WAF team the exception spec from the allowlist page (paths + Atlan NAT IPs). The "support ID" in the block page lets them find the exact rule that fired.
Opening ticket that gets solved fast
Include these six things - they routinely turn a multi-day exchange into one reply:
- Your Atlan tenant URL and the failing workflow run link
- Tableau Cloud or Server (+ Server version if known)
- Auth method (PAT / basic / JWT) and when the credential was last rotated
- The exact error text from the workflow logs (not just "test failed")
- Whether Test Authentication passes right now, retried as an Atlan admin
- Whether it ever worked - and what changed around the time it stopped (Tableau upgrade? cert renewal? someone left?)
Other known issues
What are known limitations of Tableau connector?
Atlan currently doesn't support the following:
- Crawling Tableau flows when using the JWT bearer authentication method, due to limitations at source.
- Populating Tableau popularity metrics when using the JWT bearer authentication method or when crawling Tableau Server, due to limitations at source.
- Crawling tags from Tableau.
- Cataloging Tableau Pulse, stories, and views.
- Parsing custom SQL queries, where all tables referenced (whether in the main query or subqueries) are considered as upstream lineage for the asset.
Why does Atlan require Site Administrator Explorer role in Tableau?
Atlan requires the Site Administrator Explorer role in Tableau to extract data source fields and calculated fields. It isn't possible to fetch data source fields and calculated fields with the Viewer role in the current version of the Tableau Metadata API. Atlan uses this data to generate granular column-level lineage across data sources and SQL assets. To extract lineage for assets in Tableau, the user must have the Site Administrator Explorer role.
Is lineage available for Tableau custom SQL data sources?
Yes, Atlan can parse custom SQL queries in Tableau to generate lineage between the data source and tables. Lineage is available for tables from all SQL sources. However, column-level lineage is currently not supported.
Why is upstream lineage missing for Tableau data sources?
If your Tableau data source is in paused state, the Tableau Metadata API may fail to provide the requisite metadata on source databases and tables for Atlan to generate upstream lineage. Restart your Tableau data source and verify that it remains active while crawling Tableau. This permits Atlan to fetch the requisite metadata to generate upstream lineage for data sources.
Why is there discrepancy in asset count between Tableau and Atlan?
- Dashboards - the Tableau UI doesn't display a unique count of dashboards. Dashboards in Tableau are represented in collections of one or more views. These may have same names as the views but are independent objects. Hence, the total count of these views in Tableau doesn't match the dashboard count in Atlan. Atlan sources the dashboard count from the Tableau API, which is the only reliable way to fetch the dashboard count.
- Data sources - embedded data sources aren't reported on the Tableau UI. However, in Atlan, data sources can be filtered to show only published data sources, which matches the count of data sources on the Tableau UI.
Can users who don't have access to dashboards still see preview?
Users can only see asset previews if the following conditions are met:
- They have the necessary permissions in both Tableau and Atlan.
- They're logged into Atlan and Tableau on the same browser.
Therefore, if a user lacks the permission to view a dashboard in Tableau, they won't be able to view the dashboard preview in Atlan. Even if they do have the necessary permissions, they need to be logged into Tableau on the same browser as their Atlan instance for asset previews to work.
Why can I not see previews for my Tableau assets?
- Your Tableau assets are updated with previews during the next run of your Tableau workflow. If you have run the workflow and still don't see the previews, try rerunning the workflow. Once you've rerun the workflow, the previews become visible to all eligible users.
- If you're using Tableau Server with clickjack protection enabled and your Tableau instance URL is of a different origin than the Atlan instance URL, the asset previews won't load due to a same-origin error from the browser. You need to disable clickjack protection to permit the Tableau asset previews to load.
Is certified status in Tableau mapped to certificates field in Atlan?
Yes, the isCertified status for published data sources in Tableau is mapped to the certificates field in Atlan.
Is owner field in Tableau mapped to owners field in Atlan?
No, the asset owner in Tableau is displayed as the source owner in the Overview section of the asset sidebar in Atlan. This is also only available for Tableau projects, flows, workbooks, and published data sources.
Tableau has retired metrics methods in API 3.22, hence source owner attribute for metrics isn't supported in Atlan.
Why doesn't column name in Atlan match header in my Tableau workbook?
Atlan reads field names from the Tableau Metadata API, which returns the underlying source field name (for example, Volume), not the workbook-level display alias rendered in a worksheet or dashboard (for example, Direct Volume). Tableau's Metadata API doesn't expose workbook-level aliases to third-party tools, so columns renamed at the workbook level appear in Atlan under their source field name.
Why are popularity metrics not showing for my Tableau assets?
If Tableau popularity metrics are missing for some or all of your Tableau assets, check the following:
- Source must be Tableau Cloud. Tableau Server doesn't expose the Content Exploration API used to fetch view counts, so popularity is only available for Tableau Cloud sites.
- Authentication method must be PAT or Basic. JWT bearer authentication can't call Tableau's usage statistics endpoints. Tableau Cloud documents the access scope for these endpoints as
Not available, and per the Connected Apps scopes documentation, methods without a listed scope can't be called by a Connected App JWT. Switch to personal access token or basic authentication to enable popularity. - User must have the Site Administrator Explorer role. Tableau filters usage statistics results by what the authenticated user can see. A non-admin user receives data only for content they own or have Read permission on, so popularity appears partial or empty.
- Tableau REST API version must be 3.17 or higher. Earlier versions don't include the Content Exploration API. Verify the version using the Server Info endpoint.
- Asset must be published data source, workbook, dashboard, worksheet, or flow. Embedded data sources, projects, calculated fields, and data source fields don't have independent view counts in Tableau.
- Asset must have at least one view recorded. Newly published assets that no one has viewed don't have popularity metrics.
If all of these conditions are met and popularity is still missing, rerun the Tableau workflow.
Why is the view button unavailable for a Tableau asset?
The View in Tableau button may be unavailable due to:
- Insufficient permissions to access the Tableau content
- The Tableau server being inaccessible from your current network
- Authentication issues between Atlan and Tableau
- The specific asset being moved or deleted in Tableau
Check your Tableau permissions and network connectivity, or contact your Tableau administrator.