> ## Documentation Index > Fetch the complete documentation index at: https://docs.dqlabs.ai/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Common errors when connecting to Prizm, deploying agents, and using the platform — and how to resolve them. Use this page to diagnose connection, permission, deployment, and platform issues. For live scan progress, navigate to **Settings → Connectors → Logs**. If you can't resolve your issue here, [contact DQLabs support](mailto:support@dqlabs.ai). **Job naming on this page.** Some sections below refer to the **Catalog** job — this is the same job the current documentation and product UI call **Technical**. If a job name here doesn't match what you see in the product, see the naming mapping table in the [FAQ](/faq) or the full current job list in [Scheduling](/architecture/scheduling). *** ## Connection & Authentication Errors **Error: "Invalid account identifier" or connection times out immediately** The account identifier format must exactly match your Snowflake deployment. Use the locator format without the `https://` prefix or `.snowflakecomputing.com` suffix. | Deployment | Correct format | Common mistake | | :------------- | :------------------------ | :----------------------------------------- | | AWS US East | `xy12345.us-east-1` | `xy12345.us-east-1.snowflakecomputing.com` | | Azure East US | `xy12345.east-us-2.azure` | `xy12345.azure` | | GCP US Central | `xy12345.us-central1.gcp` | `xy12345.gcp` | To find your account identifier in Snowflake: navigate to **Admin → Accounts**, hover your account name, and copy the locator shown. *** **Error: "Incorrect username or password" / "JWT token is invalid" (Key Pair)** * **Username & Password**: Confirm the service account is not locked (`SHOW USERS LIKE ''` → check `locked_until_time`). * **Key Pair**: Verify the public key is correctly assigned: `DESC USER ` and check `RSA_PUBLIC_KEY_FP`. If mismatched, re-run `ALTER USER SET RSA_PUBLIC_KEY=''`. Ensure the private key file uploaded to Prizm matches the registered public key. * **OAuth**: Confirm the redirect URI in the Snowflake security integration exactly matches the URL shown in the Prizm connection form — including trailing slashes and protocol (`https://`). *** **Error: "IP address not allowed" or connection blocked by firewall** Your Snowflake account may have a network policy restricting inbound IPs. Add Prizm's egress IP range to the Snowflake network policy: ```sql theme={null} -- View your current network policy SHOW NETWORK POLICIES; -- Add Prizm IP range to an existing policy ALTER NETWORK POLICY SET ALLOWED_IP_LIST = ( '', '' ); ``` Contact your Prizm platform team or administrator to obtain the egress IP addresses for your deployment. *** ## Permission Errors **Error: "Insufficient privileges" on catalog scan** Run the following to verify the role has the minimum required grants: ```sql theme={null} -- Check what the role can access SHOW GRANTS TO ROLE PRIZM_ROLE; -- Verify the role is assigned to the service account SHOW GRANTS TO USER ; ``` The most commonly missing grants are: | Missing grant | Symptom | | :--------------------------------- | :----------------------------------------------------- | | `USAGE ON WAREHOUSE` | All jobs fail immediately | | `USAGE ON DATABASE` | Database not visible in catalog | | `SELECT ON TABLE` | Tables cataloged but profiling fails | | `IMPORTED PRIVILEGES ON SNOWFLAKE` | Tag sync, lineage, and performance metrics unavailable | | `MONITOR ON PIPE` | Pipeline observability jobs fail | Re-run the prerequisites SQL from the [Setup page](/sources/snowflake/setup) for any database with missing grants. *** **Error: "Object does not exist or not authorized" on ACCOUNT\_USAGE views** This means `IMPORTED PRIVILEGES` on the `SNOWFLAKE` database was not granted, or was granted after the connector was created. Re-grant it and trigger a manual rescan: ```sql theme={null} GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE PRIZM_ROLE; ``` Then go to **Settings → Connectors**, select the connector, and trigger a manual scan. *** ## Performance & Timeout Errors **Catalog or profile job times out on large databases** Large Snowflake accounts (500+ tables or 50,000+ rows per table) can cause catalog and profile jobs to run longer than expected. Recommendations: * Use a dedicated warehouse for Prizm rather than a shared one, to avoid queue contention. * Start with **X-Small** or **Small** warehouse size for catalog and observability jobs. Increase to **Medium** only if profile jobs on wide tables time out. * Narrow the asset scope (exclude `DEV_*`, `SANDBOX_*`, `TEMP_*` schemas) to reduce the number of objects Prizm processes per run. * Stagger job schedules — avoid running all four job types at the same time. *** **Profile job skipped for a table** A profile job is skipped when the row count is unchanged since the last run, or when the existing profile is newer than the table's `last_altered_on` timestamp. This is normal incremental behavior. To force a re-profile, trigger a manual profile run from the asset page. *** **Assets appear in Snowflake but not in Prizm** Work through this checklist: 1. The asset's database and schema match the **Include** patterns in the connector scope. 2. The asset is not matched by an **Exclude** pattern. 3. `PRIZM_ROLE` has `USAGE` on the schema and `SELECT` on the table. 4. The Catalog job has completed at least one full run since the asset was created — check **Settings → Connectors → Logs** for the last successful Catalog job timestamp. 5. If the table was just created, wait for the next scheduled Catalog run or trigger a manual scan. Prizm catalogs TABLE and VIEW object types from Snowflake. Dynamic Tables, Stored Procedures, and External Tables are not currently included in the catalog. *** ## Tag Sync Errors **Tags defined in Snowflake are not appearing in Prizm** * Confirm `IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE` is granted (required for `ACCOUNT_USAGE.TAGS` and `TAG_REFERENCES`). * Tag sync runs as part of the Catalog job (daily by default). Check the last Catalog job run time in **Settings → Connectors → Logs**. * Enterprise-only: confirm the Snowflake account is on Enterprise edition or above, as `TAG_REFERENCES` in `ACCOUNT_USAGE` requires it. *** **Bi-directional tag sync fails (Prizm → Snowflake)** The Prizm service account must hold the `SNOWFLAKE.TAG_ADMIN` privilege for write-back: ```sql theme={null} GRANT DATABASE ROLE SNOWFLAKE.TAG_ADMIN TO ROLE PRIZM_ROLE; ``` *** ## Alerts & Metrics **I see 0 alerts but expected some** Alerts are only generated when a metric threshold is breached. If no metrics have been configured, Prizm has no rules to evaluate. * Navigate to the asset and confirm metrics are defined and set to **Active**. * Verify the evaluation schedule is active under **Settings → Connectors**. * Check the time window you're viewing — alerts outside the selected period won't appear. *** **An alert shows a high percent change but the data looks fine** Two common explanations: 1. **The baseline needs recalibration.** Prizm compares values against a historical baseline. If data has legitimately shifted (migration, seasonal change), the baseline may no longer reflect the expected range. Contact your administrator to recalibrate. 2. **The triggered column is not the one you expect.** Review the **Drift Status** column and metric name in the alert details — it may be a different column than the one you inspected. *** **A metric I created isn't producing results** * Confirm the metric is set to **Active** status. * Check whether the metric's scope matches an asset that is in the connector's Include scope. * For SQL-based (Query) metrics, run the query manually in your data source to verify it returns a result. * Review the last job run log under **Settings → Connectors → Logs** for errors related to metric execution. *** ## Agent Deployment **Agent pod is stuck in CrashLoopBackOff** ```bash theme={null} kubectl logs -n app --previous kubectl describe pod -n app ``` Common causes: | Cause | Fix | | ------------------------------- | --------------------------------------------------------------- | | Wrong image tag | Verify the tag against what the Prizm team provided | | Missing `NATS_PASSWORD` env var | Check the secret: `kubectl get secret prizm-nats-secret -n app` | | Registry unreachable | `nc -zv 443` from inside the pod | | Wrong `NATS_HOST` | Verify against NATS connection details from Prizm | *** **Agent pod is Running but not receiving any jobs** The most common cause is a mismatch in `NATS_ENVIRONMENT` between the agent and the Prizm platform. ```bash theme={null} # Kubernetes kubectl exec -n app -- env | grep NATS_ENVIRONMENT # Docker docker inspect | grep NATS_ENVIRONMENT ``` The value must exactly match the tenant name provided by the Prizm team. Confirm the NATS subscriber started successfully: ```bash theme={null} kubectl logs -n app --tail=30 | grep NATS ``` *** **NATS connection fails — agent can't connect on port 443** Test connectivity from inside the pod or VM: ```bash theme={null} nc -zv 443 ``` If this fails, check the outbound WSS 443 rule for your platform: * **AWS EKS**: Security Group egress rules on the EKS node group * **AKS**: NSG egress rules on the AKS subnet * **GCP GKE**: VPC Firewall egress rules on the node pool * **On-Prem / VM**: OS-level firewall (`ufw`) and network policy If `nc` succeeds but the agent still fails, verify `NATS_TLS_INSECURE=true` is set. *** **ImagePullBackOff on Kubernetes** ```bash theme={null} kubectl describe pod -n app ``` Check the Events section for the pull error: | Platform | Cause | Fix | | -------- | ----------------------- | ----------------------------------------------------------------- | | On-Prem | Missing ACR pull secret | `kubectl get secret acr-pull-secret -n app` — recreate if missing | | AWS | Wrong ECR image tag | Verify tag exists in ECR Public | | AKS | Wrong image tag | Verify tag against Prizm-provided values | | GCP | Registry host mismatch | Confirm Artifact Registry host with Prizm team | *** **Agent stopped working after NATS credential rotation** ```bash theme={null} # Delete and recreate the secret with new credentials kubectl delete secret prizm-nats-secret -n app kubectl create secret generic prizm-nats-secret \ --from-literal=NATS_USERNAME=nats \ --from-literal=NATS_PASSWORD= \ --namespace app # Rolling restart all agent pods kubectl rollout restart deployment -n app ``` For Docker deployments, stop and re-run each container with the updated `NATS_PASSWORD` env var. *** ## Self-Hosted Deployment **install.sh fails or services don't come up after install** ```bash theme={null} docker stack services prizm docker service logs -f prizm_nginx docker service logs -f prizm_ray ``` Common causes: | Symptom | Likely cause | Fix | | ---------------------------- | -------------------------- | --------------------------------------------------------------------- | | Services show `0/1` replicas | Image pull failure | Verify `docker login` succeeded; redeploy with `--with-registry-auth` | | `nginx` fails immediately | Port 80/443 already in use | Check `sudo netstat -tlnp \| grep '80\|443'` and free the ports | | `ray` keeps restarting | Insufficient RAM | Ensure VM has 16+ GB RAM for production | | Stack not created | Swarm not initialized | `install.sh` initializes Swarm — re-run if it exited early | *** **UI is on HTTP but I've already run a TLS setup script** ```bash theme={null} # Confirm ACCESS_SCHEME was updated grep ACCESS_SCHEME ~/docker-infra/.env # Force NGINX to reload docker service update --force prizm_nginx # Check NGINX logs for certificate errors docker service logs -f prizm_nginx ``` If NGINX logs show `SSL_CTX_use_certificate_file() failed`, the certificate is not valid PEM. Re-run `./scripts/customer-provided/setup.sh` and verify `fullchain.pem` begins with `-----BEGIN CERTIFICATE-----`. *** **Certificate and private key do not match** Verify the match manually: ```bash theme={null} openssl x509 -noout -modulus -in nginx/certs/fullchain.pem | md5sum openssl rsa -noout -modulus -in nginx/certs/privkey.pem | md5sum # Both hashes must be identical ``` If they differ, request the correct key/cert pair from the issuer. *** **Ray URL returns 502 Bad Gateway** ```bash theme={null} docker service update --force prizm_ray # Wait ~45 seconds, then retry the Ray URL # Clear Redis leader keys after restart REDIS_CID=$(docker ps --filter label=com.docker.swarm.service.name=prizm_redis --format '{{.ID}}' | head -1) docker exec "$REDIS_CID" redis-cli -a "$REDIS_PASSWORD" \ DEL leader:job_run_scheduler leader:job_scheduler ``` *** **docker login fails or pulls return 401 Unauthorized** | Registry | Likely cause | Fix | | ---------------- | -------------------------------- | ----------------------------------------------------------------------- | | AWS ECR | Token expired (\~12 hours) | Re-run `aws ecr get-login-password \| docker login ...` | | Any registry | Wrong `REGISTRY` host in `.env` | Confirm host with Prizm team; strip path after first `/` for login host | | Harbor / generic | Robot account token expired | Regenerate token in registry console | | ACR | Service principal secret expired | Rotate secret in Azure AD; re-run `docker login` | After re-authenticating, redeploy with `--with-registry-auth`: ```bash theme={null} set -a; source ~/docker-infra/.env; set +a docker stack deploy --with-registry-auth -c docker-stack.yml prizm ``` *** ## Integrations **Jira tickets are not being created from Prizm issues** * Confirm the Jira integration is enabled under **Settings → Integrations → Jira**. * Verify the API token has not expired. Regenerate it in Jira under **Account Settings → Security → API tokens** and update it in Prizm. * Check that the configured Jira project key exists and the token owner has permission to create issues in that project. * Confirm the issue type (Bug, Task, etc.) configured in Prizm exists in the target Jira project. *** **Slack / Teams / Google Chat notifications are not arriving** Test the webhook manually: ```bash theme={null} curl -X POST -H 'Content-type: application/json' \ --data '{"text":"Prizm test notification"}' \ ``` If the test succeeds but notifications don't arrive, check the alert routing rules in Prizm — notifications only fire for alerts meeting the configured priority threshold. For Microsoft Teams, confirm the incoming webhook connector is still installed on the target channel. *** **Vault integration — credentials not being picked up after rotation** * Confirm the secret path in Prizm exactly matches the path in your secrets manager. * For HashiCorp Vault with AppRole authentication, verify the AppRole token has not expired. * For AWS Secrets Manager, confirm the IAM role has `secretsmanager:GetSecretValue` permission on the rotated secret's ARN. * Trigger a manual connector test in Prizm after rotation to confirm the new credentials are being read correctly. *** ## MCP & Access Tokens **AI client can't connect using an MCP access token** * Confirm the token was generated with `generated_for: "MCP"` — standard API tokens cannot be used for MCP connections. * Verify the `mcpServers` config block in your AI client matches the format provided in Prizm, including the correct server URL and `Authorization: Bearer ` header. * Check that the token has not expired. MCP tokens have a configured TTL — regenerate and replace if expired. *** **MCP tools are returning permission errors** MCP tokens are scoped to specific tool sets at generation time. If a tool call returns a permission error: * Review the token's scope in **Settings → Access Tokens** — the token may not include the required tool category. * Generate a new token with the required tool scopes and update the AI client configuration. * Internal metrics tools (`create_metrics`, `create_alerts`, `create_profiles`) require elevated scope — confirm with your Prizm administrator. *** ## Where to Find Logs | Log location | What it shows | | :----------------------------------- | :----------------------------------------------------------- | | **Settings → Connectors → Logs** | Job run history, status (success/failed), start/end times | | **Asset page → Audit tab** | Per-asset scan history and metadata change events | | **Alert page** | Fired alerts with threshold, deviation, and priority details | | `docker service logs -f prizm_nginx` | Self-hosted: NGINX access and TLS errors | | `kubectl logs -n app` | Agent deployment: agent startup and NATS connection logs | If a job shows as failed and the error is not covered here, contact Prizm support with the connector ID and the timestamp of the failed run. *** ## Next Steps Common questions about Prizm features, deployment, and integrations. Definitions for key terms used throughout the documentation.