Troubleshoot CAT
Something does not work and the message is not enough. CAT logs what it does — where the log is and how to turn it up depends on the tool; the usual suspects are the same everywhere.
Read the log
CAT can fail at any point — reading the project file, loading a list of tests from a database, connecting to a data source, running a query, writing an output — and the log says which, in order, with the error the provider returned. It is the first place to look.
| Tool | Where the log is | Turn it up |
|---|---|---|
| CAT Studio | the Logs page in the left bar | — (always on) |
| CAT CLI | the console, and Documents\CAT\Logs\cat-log.log; off by default |
-l Information, or -l Debug |
| PowerShell module | the console, and Logs\ next to the project file (Documents\CAT\Logs\ before a project is open); Information by default |
-LoggingLevel Debug on Invoke-CatProject / Open-CatProject |
| Python module | standard output, and Documents\CAT\Logs\ (./CAT/Logs/ on Linux) |
logging_level=cat.LoggingLevel.DEBUG on the first call |
In a pipeline or a scheduled task CAT runs under another account — its Documents\CAT\Logs\ is that account’s. The last file is the one you want; in PowerShell:
Get-ChildItem "$([Environment]::GetFolderPath('MyDocuments'))\CAT\Logs" | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content
The usual suspects
- A value still has percent signs in it —
%DWH_CONNECTION_STRING%reaching the provider as text — the environment variable is not visible to the process: created after the session started, misspelled, or not mapped into the pipeline step. Use environment variables has the check. - “Unexpected token” on a line of the project file — a value starting with
%or*that is not in quotes, or wrong indentation; the line number is in the message. - The data source works in Studio and not in the pipeline — a different account: the database login, the license key, the environment variables are all per account. See Integrations.
- A test ends with
Error, notFailed— the query never ran to a verdict: the provider’s message (invalid object, login failed, timeout) is in the test’s message and in the log; see Results. - The run is refused before any test — the sign-in and plan check: no token or key, a plan that does not allow the tool, the output format or the unattended run; every tool names the reason (CAT CLI also with an exit code
2–7). Compare plans · Apply a license key. sets matchfails on rows that look equal — order: both sets must be sorted the same way, orSort data: true; see Order and key.
Still stuck
Use the Get Help button on the right of this page, and attach the log — with Maximum errors logged: 0 on the tests if the log must not carry data.