Skip to main content
The features described in this article are in public preview and may change.
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.

​
Errors while registering

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.
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.
Symptoms
  • The API returns HTTP 409, and no items in the request are created.
Cause
  • The externalId already exists in the project. This endpoint is create-only; it does not update an existing source.
  • Or two items in the same request use the same externalId.
Resolution
  1. If the externalId already exists, delete that source and register a replacement, or use a new externalId.
  2. If the items array repeats an externalId, keep only one of each.
  3. Retry the request.

​
Errors when a job runs

Job failures often wrap the cause like:
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. Delete the external data source and register a replacement with the updated secret, then run the transformation again.
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.
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.
Symptoms
  • The job fails with:
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}.
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.
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.

​
Errors in SQL

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.
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 and SQL patterns and best practices.

​
Limits

Default volume and concurrency limits for this path are Cognite-managed. There is no customer configuration page for these limits.
Symptoms
  • The job fails with:
Cause
  • The project exceeded the Cognite-managed concurrency limit for OneLake reads.
Resolution
  1. Reduce concurrent transformations that read OneLake.
  2. Contact Cognite Support to request a higher concurrency limit.
Symptoms
  • The job fails with:
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 to request a higher read volume limit.

​
Known limitations

Symptoms
  • ext_onelake returns more rows than Fabric Spark SQL or the SQL analytics endpoint.
  • Extra rows are older versions after MERGE, UPDATE, or DELETE.
  • Rows deleted in Fabric can still appear. ROW_NUMBER() does not drop them.
Cause
  • The table uses deletion vectors, which ext_onelake does not yet apply, so removed rows are still read.
ResolutionChoose the option that fits your access to the source table:
  1. Purge at the source (preferred). In Fabric, run OPTIMIZE, or REORG TABLE table_name APPLY (PURGE) then VACUUM, before the transformation runs. Re-run the transformation and confirm the row count matches Fabric.
  2. Source table is a shortcut you cannot maintain. If the table is a OneLake shortcut to a lakehouse or warehouse in another workspace, REORG fails because the source owns the physical files. In Fabric, not in Transformations SQL, copy the data into a lakehouse you own with a Spark notebook or pipeline. Fabric applies deletion vectors on read. Then point ext_onelake at the copy:
  3. De-duplicate in the transformation (partial). Keep only the latest version per key. This suppresses duplicate versions but does not remove fully deleted records. Replace equipment_id and last_updated_at with your key and version columns:
    A record deleted in Fabric has no newer version, so its masked row can still appear as rn = 1. Use option 1 or 2 when deletes must be reflected.
For background, see Known limitations.

​
Further reading

Last modified on September 9, 2026