Troubleshooting
Symptoms → cause → fix. Every entry below is a failure mode we have actually
seen; error messages are quoted as the tool prints them. First reflex when
something is off: tca verify — it checks config, secret, sign-in and
Admin Insights access with one command.
Sign-in and connectivity
"Signin Error … check the PAT name, the TCA_PAT_SECRET environment variable, and the site name"
Tableau rejected the sign-in (HTTP 401). In order of likelihood:
- Wrong site name. The
siteincollector.tomlmust be the contentUrl — the part after/site/in your browser URL — which often differs from the display name. Real example: display namesimboli-dev-820124, contentUrlsimbolidev820124(dashes stripped). A wrong site gives a 401 even with a perfectly valid PAT. - PAT name mismatch.
pat_namemust be the token's name exactly as shown under My Account Settings → Personal Access Tokens — not the secret, not your username. - Expired PAT. Tableau Cloud PATs expire after 15 days without use
(and at their configured expiry). Create a new token and re-export
TCA_PAT_SECRET. - Stale environment variable.
echo ${#TCA_PAT_SECRET}should print a plausible length (~50+). Remember:exportonly lives in the current terminal window.
"Network error … nodename nor servname provided, or not known"
DNS could not resolve the host — almost always a malformed pod. It must be
the bare pod name (10ax, prod-uk-a, eu-west-1a): the first label of
your Tableau Cloud hostname, nothing more.
"pod must be the bare pod name (e.g. '10ax' …)"
Same as above, caught earlier: you put a full hostname or URL in pod.
Use just the first label.
"The TCA_PAT_SECRET environment variable is not set"
Set it in the same terminal you run tca from —
export TCA_PAT_SECRET='<secret>' in bash/zsh,
$env:TCA_PAT_SECRET = '<secret>' in PowerShell. Either form lasts only for
that terminal session, so a new window (or a scheduled task) needs it set
again. It is never read from files by design.
The package file
"… is encrypted but no key was provided. Set the TCA_DB_KEY environment variable." / "Wrong encryption key"
The file was created with encryption: every open needs the same passphrase in
TCA_DB_KEY. There is no recovery without it — the passphrase you chose at
creation is the only key. (If it is truly lost, the data is gone: delete the
file and re-collect; see the pseudonym warning below.)
"… is in use by another process. Is another tca run in progress?"
DuckDB allows one writer at a time. Close other sessions on the same file
(duckdb CLI, DBeaver, a running tca collect). For browsing while keeping
the file available, attach read-only:
ATTACH 'site.duckdb' AS audit (ENCRYPTION_KEY 'passphrase', READ_ONLY);
"'file.duckdb' belongs to site 'X' … but this run targets 'Y'"
One package file per site, enforced. Point database in collector.toml to
a different file for the second site.
"… written by a newer collector than this one … Update tableau-cloud-audit and retry"
The file's schema version is ahead of the installed collector. Update the collector; never downgrade a file.
"Trying to read a database file with version number N, but we can only read versions between X and Y"
The full DuckDB error (here: a DuckDB 1.5 CLI opening a file written by duckdb 2.0):
IO Error: Trying to read a database file with version number 999, but we can only read versions between 64 and 68.
The database file was created with an newer version of DuckDB.
The DuckDB opening the file is older than the one that wrote it. A
DuckDB file's storage format is fixed for life when the file is created, and
older readers cannot open newer formats. tca diagnostics shows both sides
at a glance: the collector's duckdb version and the file's storage format
(duckdb 2.0.0 (file storage v1.2.0+)).
- Exports and unencrypted package files are created in the
v1.2.0format, readable by any DuckDB ≥ 1.2 (February 2025), whichever duckdb the collector runs on. A DuckDB 1.0 or 1.1 reader stops withTrying to read a database file with version number 65, but we can only read version 64: update it. Collector releases 0.2.1–0.2.3 usedv1.0.0(readable by ≥ 1.0, but with the raw JSON stored uncompressed, 3-4x larger); releases up to 0.2.0 did not pin the format, so on duckdb 2.x they wrote files only DuckDB ≥ 2.0 can read. For an export, update the collector and runtca exportagain: every export is a new file, so it gets the portable format. An existing package file keeps its format: open it with a DuckDB at least as new as the one that created it. - Encrypted package files cannot be pinned: their format is set by
DuckDB's encryption. A file encrypted by duckdb 1.5 or later needs a
reader ≥ 1.5. Update the reader (
brew upgrade duckdb, or the driver in your GUI client). The encrypted file is never meant to leave your machine anyway: the plain export is the one that travels.
My GUI client (DBeaver, …) shows an empty "memory" database
The connection did not actually open your (encrypted) file — you are looking
at an in-memory session. In a SQL editor run the ATTACH above, then refresh
the tree: the file appears as its own catalog. Requires a DuckDB driver ≥
1.4 (encryption support) — and ≥ 1.5 if the collector runs on duckdb 1.5
or later, whose encrypted files 1.4.x cannot read (see the version-number
error above); update it via the client's driver manager.
zsh: command not found: duckdb
The Python package used by the collector does not ship the CLI shell.
brew install duckdb, or just use tca summary / tca peek.
Collecting
The run stopped mid-way (Ctrl-C, crash, network drop)
Nothing is lost: every landed page is already committed.
tca collect --resume
continues the interrupted run, skipping what was collected — including the
per-item API calls. A new tca collect (without --resume) instead starts a
fresh run and marks the interrupted one aborted.
"N Personal Space workbook(s): permissions not queried"
Expected, informational. Personal Space content cannot be shared, so it has no explicit permission rules, and Tableau Cloud refuses the permissions query on it even to site administrators. The collector recognises those workbooks from the workbook listing and skips the call; the count goes in the run notes.
"⚠ N item(s) refused the query (403/404) and were skipped"
Expected. Some content refuses its query even to site administrators. The items are counted in the run notes and skipped; everything else proceeds.
"⚠ N item(s) kept failing with a server error (5xx) and were skipped"
Tableau answered a per-item call (a permissions or connections query on one
workbook or data source) with a server error on every retry. It is a fault on
Tableau's side tied to that item — seen live on a Personal Space workbook,
which answered 500 instead of 403 (those are no longer queried at all) —
so the collector skips it, lists the
failed calls under the warning and in the run notes, and finishes the run.
Skipped items are not stored, so the next tca collect asks for them again.
If three items in a row fail this way, the collector stops instead: that
pattern means Tableau itself is failing, and a run marked ok with whole
loops missing would be worse than no run. The run stays resumable — retry
later with tca collect --resume.
"⚠ Admin Insights datasources not found …"
The Admin Insights project is provisioned the first time an administrator opens it in the browser. Open it once, wait for the datasources to appear, re-run. Until then the activity module skips those sources (the REST modules are unaffected).
Tokens / Job Performance come back empty
Admin Insights extracts refresh on Tableau's daily schedule — a token created today appears tomorrow. An empty extract may also surface as a single all-null row: same cause.
"Endpoint '…' is not registered in the PII manifest" / "Safety net: …"
The privacy layer refusing to write, by design (fail loud, never leak). If you hit this on an unmodified release, a Tableau payload changed shape in a way the manifest does not cover — please open an issue with the error message (it contains no personal data).
Identities and pseudonyms
After deleting the file, pseudonyms changed
Expected, and the reason the file must be treated as an archive: the
U-#### mapping lives in the file's identity vault. Delete the file and the
next collect assigns fresh pseudonyms — history in any previously shared
export is no longer comparable. Don't delete the file; back it up.
tca peek / clear.* views show pseudonyms with empty names
The vault learns identities from /users pages. Users that appear only as
content owners or group members (e.g. Tableau system accounts hidden from the
user listing) have a pseudonym but no attributes — normal.