Skip to content

Troubleshooting

Common problems and where to look. For deeper telemetry (logs, traces, where they land) see Observability; for deploy-time issues see the Deployment checklists.

Connections

"Test" fails on a connection.

  • Re-check the credential and that the account/host/warehouse names are exact.
  • The credential must be reachable from where DataQ runs (network / firewall), not just from your laptop.
  • Use Rotate credential (re-auth) if the secret expired.
  • A missing/expired warehouse or role usually shows as a config/permission error.

A connection card shows "credential expires in Nd" / "credential expired".

Some credentials state their own expiry — an Azure SAS carries it in the token — so DataQ reads it and warns while there is still time to act. Rotate the credential (Rotate credential / re-auth) and the badge clears on the same request.

The badge is absent for most credential types, and absence is not a clean bill of health: an S3 access key, a Snowflake key-pair, and a Databricks PAT carry no readable lifetime, so DataQ says nothing rather than guessing a date. Track those expiries wherever you issue them. DataQ PATs get the same warning on the Profile → Access tokens panel, where they are stored with a known expiry.

The date is re-read daily, so a credential rotated outside DataQ (in the Azure portal, say) updates within a day rather than needing a re-save here.

Runs

A run shows failed (not just failing checks).

failed means the run couldn't execute (distinct from a check failing). The run detail now shows a redaction-safe reason — one of:

  • config — the connection or run target looks misconfigured (missing warehouse/role, or a table/path that doesn't exist). Fix the connection or the suite's target.
  • connectivity — the datasource couldn't be reached (network/DNS/TLS/timeout).
  • permission — credentials rejected or a grant is missing. Rotate the credential / add the grant.

A check is error or skip, not pass/fail. These are operational statuses, kept distinct from data failures: error = the check couldn't be evaluated (e.g. a missing column); skip = a precondition wasn't met (e.g. a batch file hasn't landed yet).

checks_total reads 0 / —. A run that failed before any check executed evaluated nothing, so its data-quality outcome is empty — that's truthful, distinct from the suite's defined check count shown on the progress view.

Dry-run returns a 502. The datasource couldn't be reached or the query couldn't run; the error detail carries a safe reason (config / connectivity / permission). The raw adapter error is never echoed (it can carry credential fragments) — check the server logs for detail.

Schedules

A scheduled run didn't fire. Confirm the schedule is enabled, the cron + timezone are right, and remember DataQ does no backfill — a missed window isn't retried, the next one runs. See Scheduling.

Triggers / orchestration

A pipeline succeeded but no suite ran. Check there's an enabled trigger binding matching (provider, pipeline/DAG/job, env) exactly, and that the webhook is configured (or the 10-minute poll fallback can reach the artifacts/REST API). Failure events alert but never trigger a run — by design. See Orchestration.

Alerts

No alert arrived for a failing run.

  • Check the suite's Notifications threshold — the default is warn-and-worse; fail-only suppresses warns.
  • Dedup is intentional: you're alerted on the first breach (and on escalation), not on every run. A red suite that's "quiet" is usually dedup working — the Results page is the ground truth.
  • Check the channel isn't snoozed for that check.
  • Confirm the channel secret/webhook is set (Settings → Webhooks / per-suite config).

Sign-in & API

  • 401 on the API or MCP = no/invalid token. For scripts, mint a fresh PAT; it expires and can be revoked.
  • SSO won't complete — confirm the IdP app registration + redirect URIs match the deployed frontend URL.

AI assistants (MCP)

  • 401 on /mcp/ = auth (expected without a token) — see MCP setup.
  • 307 = missing trailing slash; use /mcp/.
  • 421 Misdirected Request = the transport's DNS-rebind Host guard rejecting the proxied Host — a deployment-side config issue (the server allow-lists the proxied hosts); it is not something a client can fix.

Still stuck?

Check Observability for where logs/traces land, and the Runbook & FAQ for known limitations.