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

​
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. Re-register the external data source with the updated secret, then rerun the transformation.
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.

​
Further reading

Last modified on August 25, 2026