> 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/resources/nilus/troubleshooting/common-errors.md).

# Common errors

Catalog of common Nilus error messages and symptoms across pipeline modes, each paired with its likely cause and first recovery step.

This catalog collects common Nilus failure patterns and the first recovery path to try.

## Error catalog

| Error or symptom                                                                                                                                        | Likely cause                                                                                                                                                                                                                                                                           | Recovery                                                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Invalid Parameter - failure validating tenant resource: invalid resource dependency, not found: depot:<name>` (or `compute:<name>` or `secret:<name>`) | A referenced depot, compute, or secret does not exist in the tenant. Nilus validates these at apply time.                                                                                                                                                                              | Create the missing resource, or correct its name, then reapply. The error names the missing dependency and type.                                                                                                                                           |
| `Source not supported.`                                                                                                                                 | Source URI scheme, depot mapping, or pipeline mode is not supported in the current release.                                                                                                                                                                                            | Check [Sources](https://v2.dataos.info/references/resources/nilus/sources.md), then use the connector page's supported URI shape.                                                                                                                          |
| `Sink not supported.`                                                                                                                                   | Destination URI scheme or depot mapping is not supported.                                                                                                                                                                                                                              | Check [Destinations](https://v2.dataos.info/references/resources/nilus/destinations.md), then use the destination page's supported URI shape.                                                                                                              |
| `Table name must be in the format <schema>.<table>`                                                                                                     | `source_table` or `dest_table` is missing its schema or database prefix.                                                                                                                                                                                                               | Use the fully qualified form required by the connector.                                                                                                                                                                                                    |
| Authentication or permission denied                                                                                                                     | Secret projection, depot credentials, source permissions, or destination write grants are wrong.                                                                                                                                                                                       | Recheck [Secrets and projections](https://v2.dataos.info/references/resources/nilus/concepts/secrets-and-projections.md) and connector requirements.                                                                                                       |
| Empty destination table                                                                                                                                 | Wrong source object, restrictive filters, unsupported incremental cursor, or no source changes.                                                                                                                                                                                        | Confirm source row count and run with a narrow known-good object.                                                                                                                                                                                          |
| Duplicate rows                                                                                                                                          | Append strategy used for mutable entities, a missing primary key, or an unstable key.                                                                                                                                                                                                  | Use `merge` with `primary_key` where the destination supports it.                                                                                                                                                                                          |
| `ValueError: Cannot serialize value, scale of value does not match type decimal(38, 9): 4`                                                              | A Lakehouse (Iceberg) table created by a `query:` extract used `decimal(38,9)`. A SQL batch-source table then wrote decimals at another scale, or vice versa. This uses the shared SQL extract path, not only SQL Server. Switching extract styles on one `dest_table` is unsupported. | Keep one extract style per table. Use a new `dest_table`, or drop and reload. See [Schema evolution](https://v2.dataos.info/references/resources/nilus/concepts/schema-evolution.md).                                                                      |
| `ValueError: PyArrow table contains more columns: … Update the schema first (hint, use union_by_name).`                                                 | Later extraction pages introduced fields that earlier pages lacked. The destination schema was not unioned. Current Nilus versions union these fields as nullable in the same run.                                                                                                     | Retry on the current runtime. Do not drop the destination. See [Schema evolution](https://v2.dataos.info/references/resources/nilus/concepts/schema-evolution.md).                                                                                         |
| `ValueError: Could not find field with name: <column>`                                                                                                  | Sparse, all-null early pages dropped an inferred field. A later page supplied a value.                                                                                                                                                                                                 | Pin the column in `type_hints`, for example `deleted_utc: timestamp`, then rerun. See [Correctness knobs](https://v2.dataos.info/references/resources/nilus/pipeline-optimization/optimize-sink-datasets/optimize-correctness-knobs.md#type_hints-source). |
| CDC resume failure                                                                                                                                      | Source change-feed retention no longer contains the last committed offset.                                                                                                                                                                                                             | Increase retention and resnapshot the affected pipeline.                                                                                                                                                                                                   |
| CDC schema-history lookup failure                                                                                                                       | Source DDL or pipeline identity changed after history was recorded.                                                                                                                                                                                                                    | Inspect schema-history endpoints and keep CDC identity stable.                                                                                                                                                                                             |
| Metrics are stale                                                                                                                                       | Pushgateway retained old series or the runtime could not push metrics.                                                                                                                                                                                                                 | Check push age, logs, and Pushgateway connectivity.                                                                                                                                                                                                        |
| Run is slower than baseline                                                                                                                             | Source paging, destination load pressure, resource pressure, or data volume changed.                                                                                                                                                                                                   | Use [Optimizing for time](https://v2.dataos.info/references/resources/nilus/pipeline-optimization/optimizing-for-time.md).                                                                                                                                 |

## Connector-specific runbooks

* [Handling MongoDB error 286 in CDC pipelines](https://v2.dataos.info/references/resources/nilus/troubleshooting/mongodb-cdc-error-286.md)
* [Handling MongoDB warning BufferingChangeStreamCursor in CDC pipelines](https://v2.dataos.info/references/resources/nilus/troubleshooting/mongodb-cdc-bufferingchangestreamcursor.md)
* [Working with partitioned tables](https://v2.dataos.info/references/resources/nilus/batch/batch-sources/postgresql.md#working-with-partitioned-tables)

## Related docs

* [Troubleshooting](https://v2.dataos.info/references/resources/nilus/troubleshooting.md)
* [Checking logs](https://v2.dataos.info/references/resources/nilus/troubleshooting/checking-logs.md)
* [Schema evolution](https://v2.dataos.info/references/resources/nilus/concepts/schema-evolution.md)
* [Pipeline optimization](https://v2.dataos.info/references/resources/nilus/pipeline-optimization.md)


---

# 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/resources/nilus/troubleshooting/common-errors.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.
