> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK https://cognite-sdk-python.readthedocs-hosted.com/en/stable/; Atlas AI /cdf/atlas_ai/index.md; plan an Atlas AI agent /cdf/atlas_ai/concepts/atlas_ai_agent_planning.md; Flows apps /cdf/flows/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Troubleshoot Snowflake in Transformations

> Resolve common registration, SQL, and job errors when Transformations read Snowflake with ext_snowflake.

> [!WARNING]
>
> The features described in this article are in [public preview](https://docs.cognite.com/cdf/product_feature_status.md#public-preview) and may change.

Use this guide when registering a Snowflake external data source or running transformations with `ext_snowflake`.

For general transformation execution and monitoring issues, see [Troubleshooting transformations](https://docs.cognite.com/cdf/integration/guides/transformation/troubleshooting.md).

## Errors while registering

> [accordion] 403 because the feature is not enabled
>
> **Symptoms**
>
> * The API returns HTTP `403`.
> * The message indicates the feature is not enabled for the project.
>
> **Cause**
>
> The project or cluster does not have Snowflake external data sources enabled.
>
> **Resolution**
>
> Contact [Cognite Support](https://cognite.zendesk.com/hc/en-us/requests/new).

> [accordion] 403 on an otherwise valid request
>
> **Symptoms**
>
> * The API returns HTTP `403`.
> * The message indicates the subject does not have a `READ`, `WRITE`, or `USE` action.
>
> **Cause**
>
> The Cognite Data Fusion (CDF) identity is missing `transformationsExternalDataSourcesAcl` actions, or the source `dataSetId` is outside your capability scope.
>
> **Resolution**
>
> 1. Grant `transformationsExternalDataSourcesAcl` with the actions you need (`READ`, `WRITE`, `USE`).
> 2. If the source has a `dataSetId`, scope the capability with `datasetScope` that includes that data set.
> 3. Retry the request with the updated group.
>
> **Prevention**
>
> Separate the Snowflake service user from the CDF token, and verify ACLs before registration.

> [accordion] Invalid or missing settings
>
> **Symptoms**
>
> * The API returns HTTP `400`.
> * A required field is empty, or the account identifier is rejected.
>
> **Cause**
>
> * `accountIdentifier`, `userName`, `roleName`, or `warehouseName` is missing.
> * `accountIdentifier` includes a URL scheme, a path, or spaces. A common case is pasting `https://myorg-myaccount.snowflakecomputing.com`.
> * `dataSetId` does not exist or is not accessible.
>
> **Resolution**
>
> 1. Supply all four values.
> 2. Use `myorg-myaccount`, with no URL.
> 3. Use a data set you can access.

> [accordion] expiryTime is out of range
>
> **Symptoms**
>
> * The API returns HTTP `400` on create or rotate.
> * The message indicates `expiryTime` is out of range.
>
> **Cause**
>
> The expiry is in the past or more than one year ahead.
>
> **Resolution**
>
> Choose a time in the future and within one year. `expiryTime` is epoch milliseconds.

> [accordion] 409: externalId already exists
>
> **Symptoms**
>
> The API returns HTTP `409`, and no items in the request are created.
>
> **Cause**
>
> * The `externalId` already exists in the project. This endpoint is create-only; it does not update an existing source.
> * Or two items in the same request use the same `externalId`.
>
> **Resolution**
>
> 1. If the `externalId` already exists, delete that source and register a replacement, or use a new `externalId`.
> 2. If the `items` array repeats an `externalId`, keep only one of each.
> 3. Retry the request.

> [accordion] Jobs fail after a successful rotation
>
> **Symptoms**
>
> * Rotate or **Generate public key** succeeds.
> * The next job fails to authenticate.
>
> **Cause**
>
> The new public key is not registered in Snowflake yet. A new key stops the existing connection until the Snowflake admin registers it.
>
> **Resolution**
>
> Copy the new public key from the integration details page and send it to your Snowflake admin. The admin registers it before the next run. See [Rotate the public key](https://docs.cognite.com/cdf/integration/guides/transformation/set_up_snowflake_connection.md#rotate-the-public-key).
>
> **Prevention**
>
> Rotate when no critical run is scheduled, with the Snowflake admin ready.

## Errors when a job runs

> [accordion] Authentication failure or invalid Snowflake credentials
>
> **Symptoms**
>
> * Preview fails with an invalid JWT token.
> * The job fails with `Authentication failure connecting to Snowflake...`.
>
> **Cause**
>
> The public key was never registered, belongs to a different connection, was replaced by a rotation, or the connection has expired.
>
> **Resolution**
>
> 1. Run `DESC USER` and confirm `RSA_PUBLIC_KEY_FP` is set.
> 2. Copy the current public key from the integration details page and send it to your Snowflake admin. See [Register the public key](https://docs.cognite.com/cdf/integration/guides/transformation/set_up_snowflake_connection.md#register-the-public-key).
> 3. Confirm the user, role, and warehouse names match the registered connection.
> 4. If the connection has expired, rotate the public key and send the new key to your Snowflake admin. Run the transformation again after the admin registers it.

> [accordion] Table not found or permission denied
>
> **Symptoms**
>
> The job fails with `Snowflake table not found or not authorized...` or `Permission denied accessing Snowflake...`.
>
> **Cause**
>
> The table does not exist, or the service role lacks privileges. Snowflake does not distinguish the two cases.
>
> **Resolution**
>
> 1. Check the database, schema, and table names, including **case**. Unquoted Snowflake names are uppercase.
> 2. Grant `USAGE` on the database, schema, and warehouse, and `SELECT` on the table.

> [accordion] Warehouse is suspended
>
> **Symptoms**
>
> The job fails with:
>
> ```text theme={"languages":{"custom":["/_languages/kuiper.json"]}}
> The configured Snowflake warehouse is suspended and could not be auto-resumed.
> ```
>
> **Cause**
>
> The warehouse is suspended and `AUTO_RESUME` is not enabled, or the service role lacks `USAGE` on the warehouse.
>
> **Resolution**
>
> 1. Set `AUTO_RESUME = TRUE` on the warehouse, or ask a Snowflake admin to resume it.
> 2. Confirm the service role has `USAGE` on the warehouse.
> 3. Rerun the transformation.

> [accordion] Account host cannot be reached
>
> **Symptoms**
>
> The job fails with `Could not reach the configured Snowflake account...` or `Could not resolve the Snowflake account host...`.
>
> **Cause**
>
> `accountIdentifier` is wrong. Connections cannot be edited in place.
>
> **Resolution**
>
> 1. Delete the connection and register it again with the account identifier, not a Snowflake URL.
> 2. Rerun the transformation.

> [accordion] Network policy rejected the connection
>
> **Symptoms**
>
> The job fails with `Snowflake rejected the connection due to a network policy...`.
>
> **Cause**
>
> A Snowflake network policy blocks CDF.
>
> **Resolution**
>
> 1. Contact [Cognite Support](https://cognite.zendesk.com/hc/en-us/requests/new) for the CDF egress IP addresses. Ask your Snowflake admin to allowlist them on the network policy.
> 2. Rerun the transformation.

> [accordion] Statement timed out
>
> **Symptoms**
>
> The job fails with `Snowflake statement timed out...`.
>
> **Cause**
>
> The query ran longer than the warehouse statement timeout.
>
> **Resolution**
>
> 1. Narrow the query, or use `is_new()` when a version column exists.
> 2. Ask a Snowflake admin to raise `STATEMENT_TIMEOUT_IN_SECONDS` on the warehouse.

> [accordion] Snowflake is temporarily unreachable
>
> **Symptoms**
>
> The job fails with `Snowflake is temporarily unreachable...`.
>
> **Cause**
>
> A transient network error.
>
> **Resolution**
>
> 1. Retry the transformation later.
> 2. Do not change connection settings solely for a transient failure.

> [accordion] Snowflake is not configured on this cluster
>
> **Symptoms**
>
> The job fails with `Snowflake is not configured on this cluster...`.
>
> **Cause**
>
> Snowflake external data sources are not configured on this cluster.
>
> **Resolution**
>
> Contact [Cognite Support](https://cognite.zendesk.com/hc/en-us/requests/new). This is not a problem with the query or the connection.

> [accordion] Unclassified Snowflake request failed
>
> **Symptoms**
>
> The job fails with `Snowflake request failed (SQLState ..., error code ...)`.
>
> **Cause**
>
> Snowflake returned an error that CDF does not classify.
>
> **Resolution**
>
> 1. Read the detail in the message.
> 2. If the cause is unclear, contact [Cognite Support](https://cognite.zendesk.com/hc/en-us/requests/new) and include the full message.

> [accordion] Cannot use external data source or missing USE
>
> **Symptoms**
>
> The job fails with cannot use external data source, or missing `USE` action.
>
> **Cause**
>
> The source `externalId` is wrong or missing, or the running identity lacks `transformationsExternalDataSourcesAcl:USE` (including data set scope).
>
> **Resolution**
>
> 1. Confirm the `externalId` in SQL matches a registered source.
> 2. Grant `USE` on `transformationsExternalDataSourcesAcl` to the identity that runs the transformation.
> 3. If the source has a `dataSetId`, ensure data set scope includes it.

## Errors in SQL

> [accordion] Invalid ext\_snowflake arguments
>
> **Symptoms**
>
> * The query fails with a message that `ext_snowflake()` expects externalId, database, schema, and table.
> * A parameter must be a string literal.
>
> **Cause**
>
> Wrong number of arguments, an argument is not a single-quoted string literal, an argument is empty, or a name contains characters other than letters, digits, and underscores.
>
> **Resolution**
>
> 1. Use four arguments, in order: `externalId`, database, schema, and table.
> 2. Pass only quoted string literals—no column references, variables, or expressions.
> 3. Use `ext_snowflake` only as a `SELECT` source.

> [accordion] is\_new with table alias only
>
> **Symptoms**
>
> * The query rejects `is_new('cursor', a)` for a Snowflake source.
> * The message indicates `is_new` with a table alias is only supported for data modeling sources.
>
> **Cause**
>
> For Snowflake, `is_new` requires a version **column**, not the table alias. The alias form is for data modeling sources (`cdf_nodes`, `cdf_edges`, `cdf_data_models`).
>
> **Resolution**
>
> 1. Pass a column such as `a.LAST_UPDATED_TIME` (or your table’s equivalent `TIMESTAMP` or epoch-millisecond `LONG` column).
> 2. See [Read Snowflake data in transformations](https://docs.cognite.com/cdf/integration/guides/transformation/read_snowflake.md) and [SQL patterns and best practices](https://docs.cognite.com/cdf/integration/guides/transformation/sql_patterns.md).

## Limits

Default volume and concurrency limits for this path are Cognite-managed. There is no customer configuration page for these limits.

> [accordion] Snowflake concurrency or read volume limit exceeded
>
> **Symptoms**
>
> The job fails because the project exceeded a Snowflake concurrency or read volume limit.
>
> **Cause**
>
> The project exceeded the Cognite-managed concurrency or read volume limit for Snowflake reads.
>
> **Resolution**
>
> 1. Reduce concurrent transformations that read Snowflake, or reduce scan volume with `is_new()` when a version column exists.
> 2. Contact [Cognite Support](https://cognite.zendesk.com/hc/en-us/requests/new) to request a higher limit.

## Known limitations

> [accordion] Deleted rows stay in CDF
>
> **Symptoms**
>
> A row deleted in Snowflake is still in the CDF destination after an incremental run.
>
> **Cause**
>
> Incremental reads return new and changed rows only. CDF does not remove the matching instances.
>
> **Resolution**
>
> Reflect deletes in the source, for example with a soft-delete flag, and filter on that flag in the transformation.
>
> For background, see [Known limitations](https://docs.cognite.com/cdf/integration/concepts/transformation/about_snowflake_transformations.md#deleted-rows-are-not-removed).

## Further reading

* [Set up a Snowflake external data source](https://docs.cognite.com/cdf/integration/guides/transformation/set_up_snowflake_connection.md)
* [Read Snowflake data in transformations](https://docs.cognite.com/cdf/integration/guides/transformation/read_snowflake.md)
* [Troubleshooting transformations](https://docs.cognite.com/cdf/integration/guides/transformation/troubleshooting.md)
* [SQL patterns and best practices](https://docs.cognite.com/cdf/integration/guides/transformation/sql_patterns.md)
