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

# Troubleshooting

Diagnose SQL Server connection, permissions, model, and runtime failures.

Start here when a Data Product on SQL Server 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                                                             |
| ----------------------------------------- | --------------------------------------------- | --------------------------------------------------------------- |
| `database "warehouse" does not exist`     | Target database missing or wrong name         | Create the database and fix `connection.database`.              |
| Login failed for user                     | Wrong password or no database user mapping    | Fix the password and confirm `CREATE USER ... FOR LOGIN ...`.   |
| String or binary data would be truncated  | Bare `VARCHAR` defaulted to length 1          | Declare explicit column lengths.                                |
| `relation raw.raw_orders does not exist`  | Missing table, grant, or external declaration | Grant `SELECT` and add `inputs.yaml`.                           |
| Plan succeeds but SSMS shows empty schema | Different login or database                   | Use the same database and a `db_datareader` login.              |
| Semantic column does not exist            | Bracket or quoting mismatch                   | Quote identifiers consistently.                                 |
| Depot not resolvable on DataOS            | Depot name mismatch                           | Match the configured `dataos://` address to the Depot manifest. |
| `PermissionError: '.logs'`                | Working directory is not writable             | Use `vulcan --log-to-stdout` or make the directory writable.    |
| `vulcan plan` runs DDL                    | Lifecycle DDL is unguarded                    | Wrap it in `@IF(@runtime_stage = 'evaluating', ...)`.           |
| Incremental reprocesses history           | Incorrect `time_column` or `unique_key`       | Align model configuration with actual columns.                  |
| Endpoint OOM on large result              | API memory is too low                         | Raise API memory and limit result size.                         |
| Too many connections                      | Workers, replicas, and BI exceed capacity     | Lower concurrency or replicas, then add a pooler.               |
| `mssql_merge_exists` throws on `EXCEPT`   | Unsupported column type                       | Disable the optimization for that table.                        |
| `pymssql` fails to build                  | Required local headers are absent             | Use the supplied wheel or `driver: pyodbc`.                     |

## Health-check queries

Run these queries to confirm the active database, login, available tables, and active sessions.

```sql
SELECT DB_NAME() AS current_database, SUSER_SNAME() AS current_login;

SELECT s.name AS schema_name, t.name AS table_name
FROM sys.tables t JOIN sys.schemas s ON t.schema_id = s.schema_id
ORDER BY s.name, t.name;

SELECT session_id, status, login_name, host_name
FROM sys.dm_exec_sessions WHERE is_user_process = 1;
```

## Recovery procedures

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

| Situation                         | Procedure                                                                      |
| --------------------------------- | ------------------------------------------------------------------------------ |
| Incremental run failed mid-window | Re-run. Time-range and partition incrementals reprocess the affected window.   |
| Table dropped manually            | `vulcan plan` detects and recreates it. Use a rebuild command if needed.       |
| Wrong database applied            | Fix the connection, verify with `SELECT DB_NAME()`, then re-run plan or apply. |
| Credentials leaked                | Rotate the password and update `.env` or the DataOS instance secret.           |
| Connection exhaustion             | Lower concurrency or replicas, add a pooler, and investigate blocked sessions. |
| MERGE deadlock between runs       | Set `concurrencyPolicy: Forbid` and stagger heavy MERGE models.                |

### Next step

Return to the [SQL Server](https://v2.dataos.info/references/engine-guide/sql-server.md) to review production readiness and related guides.


---

# 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/sql-server/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.
