Skip to main content

Troubleshooting Snowflake errors

When setting up or using a Snowflake-backed context repository in Context Engineering Studio, you may encounter errors at any stage, from initial configuration through deployment and chat. This page covers the most common Snowflake errors and how to fix them.

No connection configured​

Error

Configure a Snowflake connection first to run permission checks

A yellow banner appears when you open the preflight check panel without selecting a connection.

Cause​

No Snowflake connection has been selected in the Configure tab of Context Engineering Studio.

Solution​

Go to Configure and select a Snowflake connection before running the preflight check.

Credentials not found​

The preflight check panel fails to load entirely.

Cause​

No credentials are stored for the selected connection in Heracles (Atlan's internal credential store). The preflight check requires valid credentials to reach Snowflake.

Solution​

Contact your Atlan administrator. The administrator must link valid credentials to the connection in Heracles before the preflight check can run.

Pre-flight check failed​

Error

Pre-flight check failed

A red toast notification appears after attempting to run the preflight check.

Cause​

A network error prevented CES from reaching Snowflake during the check. This is unrelated to permission grants.

Solution​

Verify that your Snowflake account URL is reachable from the Atlan environment. If your tenant uses a private network or PrivateLink, confirm that the routing is configured correctly.

Preflight required checks failing​

The preflight check runs six categories. The three required categories block deployment if they fail. Each failed check in the UI expands to show the exact SQL to run in your Snowflake console, along with a copy button.

Connectivity check fails​

What it tests: Whether CES can reach your Snowflake instance at all.

Fix: Check your network or VPC configuration. If using PrivateLink, confirm the endpoint is active and routable from the Atlan environment.

Deploy check fails​

What it tests: Whether the Atlan service role has USAGE on the target database and schema, and WRITE access on the stage.

Fix: Run the SQL shown in the UI, for example:

GRANT USAGE ON DATABASE <your_database> TO ROLE <atlan_role>;
GRANT USAGE ON SCHEMA <your_schema> TO ROLE <atlan_role>;
GRANT WRITE ON STAGE <your_stage> TO ROLE <atlan_role>;

Cortex check fails​

What it tests: Whether the Atlan service role can invoke Cortex Analyst.

Fix: Grant the Cortex user database role:

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE <atlan_role>;

Recommended checks don't block deployment, but missing grants reduce accuracy or disable specific features.

CheckWhat it testsImpact if missing
MetadataSELECT on INFORMATION_SCHEMAAI generates from catalog metadata only, less accurate
ObservabilityAccess to QUERY_HISTORYObserve tab won't show production traces
CrawlingAtlan crawler permissions on the schemaDeployed views won't appear automatically in the catalog

Run the SQL shown in each failed check's expanded panel to resolve these warnings.

Generation failed​

The session shows a generationError state and the Build tab displays an error.

Cause​

The LLM call timed out or Atlan AI was unreachable during generation.

Solution​

Retry the generation. If the error persists, contact your Atlan administrator to verify Atlan AI connectivity.

YAML validation error after generation​

The Build tab shows an inline error with a line number and a fix hint.

Cause​

The generated YAML contains a structural issue. Common causes include:

  • Nested aggregate definitions
  • Sample values containing special characters (HTML entities, dollar signs, regex patterns)
  • Column names that don't match the actual schema
  • Naming convention mismatches, for example, mixing camelCase and underscore-separated names

Solution​

  1. Review the error location shown in the Build tab.
  2. Use the Autofix button if available, or edit the YAML directly.
  3. Remove or correct sample values that contain special characters.
  4. Compare incorrect column references with the actual table schema in the catalog.
  5. Re-deploy after correcting the YAML.

Evaluation failed​

The session shows an evaluationError state.

Cause​

Cortex Analyst returned an error for all evaluation queries. This usually indicates a problem with the YAML structure or the Cortex permission grant.

Solution​

  1. Confirm the YAML is valid, check the Build tab for any unresolved errors.
  2. Re-run the preflight Cortex check to confirm the grant is still in place.
  3. Re-run the evaluation after resolving any issues.

Evaluation query timeout​

A question in the evaluation suite is marked as failed with a timeout message.

Cause​

The Snowflake warehouse took more than 300 seconds to execute the generated SQL.

Solution​

  • Use a Large or X-Large warehouse for evaluation runs.
  • Simplify queries in your golden suite if they reference very large tables without filters.
  • Run evaluations one at a time rather than in parallel to avoid query queue buildup.

0% pass rate on evaluation​

All evaluation questions fail.

Cause​

The name: field in the YAML doesn't match the model name as deployed in the Snowflake stage. Cortex Analyst resolves models by name, and a mismatch causes every query to fail.

Solution​

Check that the name: field in your YAML exactly matches the file name used when deploying to the Snowflake stage. Correct the name and redeploy before re-running evaluation.

Deploy failed​

The session shows a deployError state and the Deploy tab shows a failure.

Cause​

Deployment can fail for several reasons:

  • The Snowflake stage write failed due to a network error or insufficient permissions
  • The JWT used to authenticate with Snowflake has expired
  • Cortex Analyst rejected the YAML due to a structural issue not caught during validation

Solution​

  1. Re-run the preflight check to identify any permission gaps.
  2. Fix any issues flagged by the preflight check.
  3. Redeploy.

JWT authentication failed​

Error

Authentication failed: {error}

Cause​

The RSA key pair used to authenticate CES with Snowflake is invalid, expired, or the Snowflake account identifier format is incorrect.

Solution​

Your Atlan administrator must re-link valid credentials in Heracles. Verify that:

  • The RSA private key in Heracles matches the public key registered in Snowflake.
  • The Snowflake account identifier uses the correct format (<org>-<account>, not the legacy format).
  • The key hasn't been rotated in Snowflake without updating Heracles.

Snowflake query failed​

Error

Snowflake query failed: {response body}

Cause​

The Snowflake REST API rejected the request. Common causes are an incorrect warehouse name, a role that doesn't exist, or a suspended warehouse.

Solution​

Check the warehouse and role specified in the connection settings. Confirm the warehouse is running and the Atlan service role has USAGE on it.

Atlas catalog publish failed​

The Deploy tab shows publishStatus: FAILED with a publishError message.

Cause​

CES deployed the model to Snowflake successfully, but couldn't register it as an entity in the Atlan catalog (Atlas). This is a connectivity issue between CES and Atlas, not a Snowflake issue.

Solution​

Retry the deploy. If the error persists, contact Atlan support, this indicates an Atlas connectivity issue that requires investigation.

Chat returns unclear intent​

The AI responds by asking for clarification instead of taking action.

Cause​

The question was too vague for the intent classifier to categorize it.

Solution​

Rephrase the question to be specific. For example, instead of "add something," use "add a metric for monthly active users." Clear, action-oriented prompts reduce classification ambiguity.

Chat returns errors​

The chat bubble shows an error response with success: false.

Cause​

Cortex Analyst couldn't process the question with the deployed model.

Solution​

  1. Confirm the YAML is valid using the Build tab.
  2. Re-run the evaluation suite to identify failing queries.
  3. Deploy a corrected version of the model before retrying.

SQL generated but no results​

Chat shows the generated SQL but returns zero rows.

Cause​

The model or golden query points to an empty table, or the query uses a date range that doesn't match the data.

Solution​

Confirm the table has data for the queried time range. If the golden query uses hard-coded date filters, update them to match your data.

Slow loading or generation​

Asset loading taking more than 30 seconds or generation taking 2–3 minutes is expected behavior for large schemas. CES fetches full column metadata for each table during asset loading, and the LLM processes all columns during generation. Don't close the tab while generation is in progress.

If evaluation is slow, each golden query executes a full SQL run on Snowflake, use a larger warehouse and run evaluations one at a time to reduce wait times.

If the preflight check hangs indefinitely, check VPC or PrivateLink routing between the Atlan environment and your Snowflake account.

See also​

Need help​

If you need assistance after trying these steps, contact Atlan Support.