> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/engine-guide/snowflake/troubleshooting.md).

# Troubleshooting

Diagnose common Snowflake and Vulcan failures, then recover production workloads.

Start here when a Data Product on Snowflake fails to plan, deploy, or run. Identify the symptom, run health checks, then recover safely.

## Failure modes

Match the observed symptom to its likely cause and recommended fix.

| Symptom                                   | Likely cause                                            | Fix                                                                      |
| ----------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------ |
| JWT token invalid on first run            | Public key is missing or the PEM and passphrase differ. | Run `ALTER USER … SET RSA_PUBLIC_KEY`; then verify the passphrase.       |
| Account identifier not found              | Account format is incorrect.                            | Use `<org>-<account>` from the console URL.                              |
| `Object 'COL' does not exist`             | A semantic model uses lowercase identifiers.            | Use UPPERCASE identifiers.                                               |
| `Table not found: SNOWFLAKE_SAMPLE_DATA…` | Cross-database source is not declared.                  | Add a triple-quoted identifier to `inputs.yaml`.                         |
| Insufficient schema privileges            | Role lacks `CREATE SCHEMA` or `CREATE TABLE`.           | Apply the service-role grants.                                           |
| `IMPORTED PRIVILEGES` required            | The sample-data share is not mounted.                   | Grant imported privileges on `SNOWFLAKE_SAMPLE_DATA`.                    |
| `Depot not resolvable`                    | Depot name does not match the resource.                 | Match the `dataos://` name to the depot manifest.                        |
| `vulcan plan` runs DDL                    | Lifecycle DDL is unguarded.                             | Wrap the statement in `@IF(@runtime_stage = 'evaluating', …)`.           |
| `Coercion failed` in a macro              | Macro parameter is annotated `: str`.                   | Remove the annotation and render with `.sql(dialect=evaluator.dialect)`. |
| `NameError: 'col' is not defined`         | Snowpark functions are imported at module scope.        | Import them inside `execute()`.                                          |
| Endpoint OOM                              | API memory is below 1.5 GiB.                            | Raise it to 3 GiB.                                                       |

## Health-check queries

Run these queries to inspect recent Vulcan activity and warehouse queueing.

```sql
SELECT query_id, query_text, execution_status,
       total_elapsed_time / 1000 AS seconds, warehouse_name
FROM snowflake.account_usage.query_history
WHERE query_tag LIKE 'vulcan:%'
  AND start_time > DATEADD(hour, -2, CURRENT_TIMESTAMP())
ORDER BY start_time DESC
LIMIT 50;

SELECT warehouse_name, COUNT(*) AS queries,
       AVG(queued_provisioning_time + queued_overload_time) / 1000 AS avg_queued_s
FROM snowflake.account_usage.query_history
WHERE start_time > DATEADD(hour, -1, CURRENT_TIMESTAMP())
GROUP BY warehouse_name
ORDER BY avg_queued_s DESC;
```

## Recovery procedures

Use the matching procedure to restore the workload without unnecessary rework.

| Situation                          | Procedure                                                                |
| ---------------------------------- | ------------------------------------------------------------------------ |
| Incremental run failed mid-way     | Re-run the workflow. Time-range models safely refresh the failed window. |
| State drifted                      | Run `vulcan plan`, or use `vulcan run --rebuild <model>`.                |
| Roll back a plan version           | Run `vulcan rollback <plan_id>`. This consumes credits.                  |
| Workflow stopped after `endOn`     | Update `endOn` and re-apply the resource.                                |
| Resource monitor suspended compute | Investigate spend, adjust `CREDIT_QUOTA`, or resume the warehouse.       |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/engine-guide/snowflake/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
