> 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/redshift/troubleshooting.md).

# Troubleshooting

Diagnose and recover from common Redshift deployment and runtime failures.

Start here when a Data Product on Redshift fails to plan, deploy, or run. Identify the symptom, validate the environment, then recover safely.

{% hint style="info" %}
**Flagged for review:** the source manual carried two overlapping tables: "Operational limitations" (nine rows) and "Failure modes & troubleshooting" (fifteen rows). Both duplicated most of the same symptoms (SSL, depot resolution, timeouts, semantic casing, stale state, VARCHAR truncation). They've been merged into the single table below, the pattern every other converted engine page uses, keeping the two rows that weren't duplicates (schema-not-found, expired `endOn`). Check the merged table against the original if you want to confirm nothing was dropped.
{% endhint %}

### Failure modes

| #   | Symptom                             | Likely cause                    | Fix                                                                                                                                    |
| --- | ----------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| F1  | SSL / connection refused            | Wrong host, port, or SSL off    | Fix the depot; enable SSL                                                                                                              |
| F2  | Schema not found                    | Target schema missing           | Create it in `before_all`, or have an admin run `CREATE SCHEMA`                                                                        |
| F3  | `permission denied for schema`      | Missing GRANT                   | Apply the schema grants in [Permissions and Grants](https://v2.dataos.info/references/engine-guide/redshift/permissions-and-grants.md) |
| F4  | Depot not resolvable                | Name mismatch                   | Align the `deploy.yaml` and `config.yaml` depot URL                                                                                    |
| F5  | `statement timeout`                 | Heavy SQL or low timeout        | Tune the SQL; raise the timeout in session                                                                                             |
| F6  | Semantic column not found           | Casing or drift                 | Match the semantic model to the physical column casing                                                                                 |
| F7  | Incremental reprocesses all history | Wrong `time_column`             | Fix the model kind config                                                                                                              |
| F8  | `MERGE` fails on key                | Type mismatch or null keys      | Fix the grain and assertions                                                                                                           |
| F9  | Plan runs DDL unexpectedly          | Unguarded lifecycle SQL         | Wrap it in `@IF(@runtime_stage = 'evaluating', ...)`                                                                                   |
| F10 | Stale apply skipped                 | Postgres state drift            | New `state_schema`, then `vulcan migrate`                                                                                              |
| F11 | API OOM                             | Low memory limit                | Raise to the 3 GiB API limit                                                                                                           |
| F12 | Rollup / transpiler error           | Missing transpiler URL or token | Configure the transpiler or disable rollups                                                                                            |
| F13 | VARCHAR truncation                  | Column too narrow               | Widen the model column types                                                                                                           |
| F14 | Disk full / skew                    | Bad dist key                    | Redesign the dist key; vacuum via admin ops                                                                                            |
| F15 | `database does not exist`           | Wrong `REDSHIFT_DATABASE`       | Fix the depot database field                                                                                                           |
| F16 | Slow after load                     | Missing stats                   | Run `ANALYZE` in `after_all`                                                                                                           |
| F17 | Workflow halted                     | Expired `endOn`                 | Update `endOn` and re-apply the Vulcan resource                                                                                        |

### Health-check queries

```sql
SELECT current_user, current_database();
SELECT schema_name FROM information_schema.schemata ORDER BY 1;

SELECT table_schema, table_name, table_type
FROM information_schema.tables
WHERE table_schema IN ('bronzev2', 'silverv2', 'goldv2', 'public')
ORDER BY 1, 2
LIMIT 100;
```

### Recovery procedures

| Situation                     | Procedure                                              |
| ----------------------------- | ------------------------------------------------------ |
| Incremental failed mid-window | Re-run the workflow; safe if idempotent for the window |
| Table dropped manually        | `vulcan plan` to detect; rebuild the model             |
| Wrong database                | Fix the depot; new `state_schema`, migrate, re-apply   |
| Password rotated              | Update the secret and depot binding                    |
| Workflow halted (`endOn`)     | Extend `endOn` in the deploy manifest                  |


---

# 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/redshift/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.
