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

# Troubleshoot Fabric OneLake in Transformations

> Resolve registration, SQL, and job errors when Transformations read Fabric OneLake with ext_onelake.

<Warning>
  The features described in this article are in [public preview](/cdf/product_feature_status#public-preview) and may change.
</Warning>

Use this guide when registering a Fabric OneLake external data source or running transformations with `ext_onelake`.

For general transformation execution and monitoring issues, see [Troubleshooting transformations](/cdf/integration/guides/transformation/troubleshooting).

## Errors while registering

<AccordionGroup>
  <Accordion title="Fabric path part must be a valid GUID">
    **Symptoms**

    * Registration fails with a message that a Fabric path part must be a valid GUID (UUID format).

    **Cause**

    * You supplied a friendly workspace or lakehouse name instead of a GUID.

    **Resolution**

    1. Use the workspace GUID from Fabric **Workspace settings** → **Workspace ID**.
    2. Use the lakehouse GUID from Fabric **Lakehouse settings** → **Item ID**.
    3. Register the external data source again with `workspaceId` and `containerId` as GUIDs.

    **Prevention**

    * Prefer GUIDs from Fabric settings or the table ABFSS path; do not use display names.
  </Accordion>

  <Accordion title="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 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 Fabric service principal credentials from the CDF token, and verify ACLs before registration.
  </Accordion>

  <Accordion title="409 duplicate externalId in the request">
    **Symptoms**

    * The API returns HTTP `409`.

    **Cause**

    * Two items in the same request use the same `externalId`.

    **Resolution**

    1. Deduplicate the `items` array so each `externalId` appears once.
    2. Retry the request.
  </Accordion>
</AccordionGroup>

## Errors when a job runs

Job failures often wrap the cause like:

```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
Failed to resolve 'ext_onelake(externalId="my-fabric-source", table="equipment")' due to <reason>
```

<AccordionGroup>
  <Accordion title="Authentication failure or invalid Fabric credentials">
    **Symptoms**

    * The job fails with authentication failure or a message to check Fabric credentials.

    **Cause**

    * The service principal cannot authenticate to Microsoft Entra ID (wrong tenant or client ID, or expired secret).

    **Resolution**

    1. Confirm tenant ID, client ID, and client secret in Entra ID.
    2. Create a fresh client secret if the previous one expired.
    3. Re-register the external data source with the updated secret, then rerun the transformation.
  </Accordion>

  <Accordion title="Permission denied: Contributor required">
    **Symptoms**

    * The job fails with permission denied accessing OneLake.
    * The message states that Viewer is not enough for API access.

    **Cause**

    * The service principal authenticates but does not have at least **Contributor** on the Fabric workspace or lakehouse.

    **Resolution**

    1. Raise the service principal role to at least **Contributor** in Fabric.
    2. Confirm the tenant allows service principals to use Fabric APIs.
    3. Rerun the transformation.

    **Prevention**

    * Do not rely on **Viewer** for OneLake API reads.
  </Accordion>

  <Accordion title="Table not found or not a Delta table">
    **Symptoms**

    * The job fails with a message that the OneLake table was not found or is not a Delta table.

    **Cause**

    * The table name does not resolve, spelling or case does not match, or the folder is not Delta format.

    **Resolution**

    1. Check table name spelling and **case**.
    2. Confirm the table is Delta under the lakehouse `Tables/` area.
    3. If the table sits under a schema folder, use the three-argument `ext_onelake` form.
  </Accordion>

  <Accordion title="Path does not exist in OneLake">
    **Symptoms**

    * The job fails with:

    ```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    Path does not exist in OneLake. Verify the workspaceId, lakehouse (containerId), and table name in your ext_onelake() source.
    ```

    **Cause**

    * The path built from the external data source and `ext_onelake` arguments does not exist.

    **Resolution**

    1. Re-check `workspaceId` and `containerId` GUIDs on the registered source.
    2. Confirm the table name (and optional schema) in `ext_onelake`.
    3. Use the three-argument form if the table is under `Tables/{schema}/{table}`.
  </Accordion>

  <Accordion title="OneLake throttling or temporary unavailability">
    **Symptoms**

    * The job fails with OneLake throttling or temporary unavailability.

    **Cause**

    * Transient Fabric or storage-layer rate limiting or outage.

    **Resolution**

    1. Retry the transformation later.
    2. Do not change connection settings solely for a transient throttle.

    **Prevention**

    * Prefer incremental loads with `is_new()` when a version column is available to reduce read volume.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Errors in SQL

<AccordionGroup>
  <Accordion title="Invalid ext_onelake arguments">
    **Symptoms**

    * The query fails with a message that `ext_onelake()` expects externalId, table name, and optionally schema.
    * A parameter must be a string literal.

    **Cause**

    * Wrong number of arguments, or an argument is not a single-quoted string literal.

    **Resolution**

    1. Use two arguments (`externalId`, table) or three (`externalId`, table, schema).
    2. Pass only quoted string literals—no column references, variables, or expressions.
    3. Use `ext_onelake` only as a `SELECT` source.
  </Accordion>

  <Accordion title="is_new with table alias only">
    **Symptoms**

    * The query rejects `is_new('cursor', a)` for a OneLake source.

    **Cause**

    * For Fabric OneLake, `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.lastUpdatedTime` (or your table’s equivalent `TIMESTAMP` or epoch-millisecond `LONG` column).
    2. See [Read Fabric OneLake data in transformations](/cdf/integration/guides/transformation/read_fabric_onelake) and [SQL patterns and best practices](/cdf/integration/guides/transformation/sql_patterns).
  </Accordion>
</AccordionGroup>

## Limits

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

<AccordionGroup>
  <Accordion title="OneLake concurrency limit exceeded">
    **Symptoms**

    * The job fails with:

    ```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    OneLake concurrency limit exceeded for project <project>: <usage>/<limit>
    ```

    **Cause**

    * The project exceeded the Cognite-managed concurrency limit for OneLake reads.

    **Resolution**

    1. Reduce concurrent transformations that read OneLake.
    2. Contact [Cognite Support](https://cognite.zendesk.com/hc/en-us/requests/new) to request a higher concurrency limit.
  </Accordion>

  <Accordion title="OneLake read volume limit exceeded">
    **Symptoms**

    * The job fails with:

    ```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    OneLake read volume limit exceeded for project <project>. Read <n> bytes, limit is <m> bytes.
    ```

    **Cause**

    * The project exceeded the Cognite-managed OneLake read volume limit.

    **Resolution**

    1. Reduce scan volume (for example 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 read volume limit.
  </Accordion>
</AccordionGroup>

## Further reading

* [Set up a Fabric OneLake external data source](/cdf/integration/guides/transformation/set_up_fabric_onelake_connection)
* [Read Fabric OneLake data in transformations](/cdf/integration/guides/transformation/read_fabric_onelake)
* [Troubleshooting transformations](/cdf/integration/guides/transformation/troubleshooting)
* [SQL patterns and best practices](/cdf/integration/guides/transformation/sql_patterns)