Troubleshooting

Troubleshooting

Symptom	Likely cause / fix
TAKT_BASE_URL is required	The env var is unset/empty in your MCP client config.
TAKT_BASE_URL must use http:// or https://	Include the scheme, e.g. https://takt.example.com.
TAKT_BASE_URL is not a valid URL	Fix the URL; it is parsed at startup.
TAKT_API_KEY is required	Set the API key minted in the Takt dashboard.
TAKT_TIMEOUT_MS must be an integer in …	Use an integer in 1000–120000.
Takt API error (401 …)	Key is wrong or revoked.
Takt API error (403 …)	Key lacks the required permission (stats:read / sites:read).
site not found	The domain is not the key's site — keys are single-site bound.
Takt API error (402 quota_api_depasse)	The API quota for your plan is exhausted.
request timed out after …ms	Raise TAKT_TIMEOUT_MS, or check connectivity to your instance.

Debug logging

Set TAKT_DEBUG=1 to log each request (method, path, query) and every retry decision to stderr. The API key is never logged.

"env": { "TAKT_BASE_URL": "…", "TAKT_API_KEY": "…", "TAKT_DEBUG": "1" }

stdout is reserved for the MCP transport, so diagnostics never appear there.

Retries and timeouts

Transient 429/5xx/network failures are retried with exponential backoff and jitter, honouring Retry-After. Tune with TAKT_MAX_RETRIES (default 2) and TAKT_TIMEOUT_MS (default 15000). For fail-fast interactive use, set TAKT_MAX_RETRIES=0.

See Configuration.