1. Choose the closest symptom

Capture these facts before changing anything

1. Failing surface: preview, interactive Spark, scheduled notebook/pipeline, SQL endpoint or a specific Power BI model.
2. Shortcut and target: consumer workspace/item, shortcut path and target workspace/item or storage path. Confirm the target exists and was not renamed.
3. Actual principal: affected user, execution identity, connection identity or item owner—not simply the person viewing the browser.
4. Authentication: passthrough or delegated shortcut; if SQL is involved, also record that endpoint’s access mode.
5. Evidence: exact error, UTC time and request/activity ID. Keep credentials, SAS query strings and tokens out of screenshots and tickets.

Reading a shortcut definition is not the same as reading its target data. Cross-tenant shortcuts do not use the same-tenant passthrough model.

2. Identify the identity that reaches the data

• Same-tenant OneLake shortcut: passthrough is the default, but delegated authentication can be selected at creation. Inspect the actual configuration.
• Cross-tenant or external shortcut: uses delegated authentication. Check that connection identity’s target access; granting every viewer Azure storage permissions is not the default remedy.
• SQL endpoint: user and delegated identity modes separately control SQL-to-OneLake access. Microsoft also documents an item-owner identity exception for Power BI Direct Lake over SQL. A Spark test does not validate every SQL/Power BI path.

Sources: shortcut security; SQL endpoint access modes.

A. Fix an internal OneLake shortcut

Start here if: the target is another Fabric item. For cross-tenant access, use the delegated branch and Microsoft’s cross-tenant setup.

A1. Passthrough: check both paths for the affected principal

1. Open the consumer item’s Manage permissions. Confirm the affected user or intended group has Fabric Read through the approved sharing/workspace model.
2. Check read access to the shortcut path and target path. Where OneLake security applies, inspect the role’s selected tables/folders and membership at both locations. For items not yet supporting OneLake security, Microsoft documents item ReadAll as the relevant data-read permission.
3. For a Viewer or read-only item recipient, verify the appropriate OneLake data role. Seeing the shortcut name does not grant data access.
4. For SQL user identity mode, apply B2’s exact principal-mapping and sync checks. That is a documented SQL hub-and-spoke requirement—not a statement that all Fabric group nesting is unsupported.
5. Make the smallest approved change, then repeat the failing read using the affected identity. Do not test only as the administrator who made the change.

A2. Delegated shortcut: check the connection identity at the target

1. Identify the configured connection and principal. For cross-tenant access, confirm the intended producer-tenant identity.
2. Have the target owner verify this identity’s read access to the exact path. Separately verify the end user’s consumer shortcut permissions.
3. Review producer and consumer OneLake policies. Delegation is not unrestricted access; Microsoft describes the result as the intersection of the relevant security at both sides.
4. For connection changes, use C’s dependency checks before replacement.

Switching an existing OneLake shortcut between passthrough and delegated authentication currently requires deleting and recreating it. That is a planned change, not the first troubleshooting step. Record the definition and downstream dependencies first. Microsoft reference.

Back to symptom choices · Verify this fix

B. Spark works, but SQL or Power BI fails

Open the consumer SQL analytics endpoint actually executing the failing query. Select Security → View data access mode. Inspect it; do not change it yet. An unrelated source endpoint is not a universal fix.

B1. Consumer SQL endpoint uses delegated identity mode

1. Confirm the caller has item Read plus required SQL permissions. Delegated mode uses SQL-layer authorization for the caller and the item owner’s identity for OneLake access.
2. Have the administrator check that owner’s access to consumer and source items/data. The caller’s successful interactive source read is not enough.
3. Inspect the source table’s OneLake row-level (RLS), column-level (CLS), or object-level security (OLS). Microsoft documents shortcut queries in delegated SQL mode as blocked when these source rules exist.
4. If OneLake filtering must apply, have the governance owner assess moving the consumer endpoint to user identity mode. If SQL-governed filtering must remain, this needs an architectural decision—not stripping source protections as an emergency fix.

B2. Consumer SQL endpoint uses user identity mode

1. Match the literal principal. If the producer role grants a user, that same principal needs Fabric Read at the consumer. If it grants a security group, that same group must have Fabric Read there; an unrelated direct grant to a member does not satisfy this documented mapping. Compare Object IDs, not just names.
2. Check data-role scope. Confirm the permitted table, folder, rows and columns. SQL table GRANTs do not replace OneLake table authorization in user identity mode.
3. Check security sync. Microsoft says changes can take up to five minutes. Use Metadata sync in the endpoint toolbar. Inspect Object Explorer → Security → Roles → Database Roles for expected OLS_-prefixed roles. These are managed roles: do not edit them manually.
4. If sync fails: check recent table/column renames or drops against role definitions. Fix stale references with the data owner rather than deleting protections.

B3. Only the Power BI model fails

Record whether the model uses Direct Lake over SQL, Direct Lake over OneLake, DirectQuery or Import, plus its connection identity/SSO configuration. Direct Lake over SQL has documented owner-identity behavior; a viewer’s successful Spark read is not a complete model test. Trace the actual model’s identity chain. For storage-mode symptoms, see the Direct Lake guide.

Sources: SQL security troubleshooting; access-mode impact; engine identity exceptions.

Back to symptom choices · Verify this fix

C. Fix an external storage shortcut

Separate three checks: consumer shortcut access, connection identity’s target authorization, and networking. Valid credentials do not bypass a firewall; a network exception does not grant data-read permission.

C1. Inspect the connection before replacing it

1. Open consumer Lakehouse Settings → Shortcut connections. Check Action required, the authentication method and how many shortcuts share the connection.
2. Verify account/container/path and identity. For SAS, check expiry, permissions and scope without exposing the token. For service principals, check tenant and credential validity. For workspace identity, confirm the correct workspace’s identity.
3. Have the storage owner check read/list authorization for that principal. For ADLS, use the documented data-role/ACL model; generic Azure Contributor is not a substitute for blob data access.
4. Repair authorization/credentials or use Replace with a reviewed connection. Microsoft says this updates all shortcuts using the old connection. Record the old mapping and test dependent shortcuts.

C2. ADLS firewall: check trusted workspace access

This branch is for Microsoft’s trusted-workspace-access pattern, not every private-networking architecture.

• The workspace needs a purchased Fabric F capacity. Trial is not supported for trusted workspace access.
• Confirm its workspace identity and Microsoft’s required setup permissions. For the straightforward read-only ADLS workspace-identity pattern, Microsoft documents Storage Blob Data Reader at storage-account scope. That scope can be broader than the intended data boundary: the storage owner must approve it or design a supported alternative.
• Configure an approved resource instance rule for the specific Fabric workspace. Microsoft documents ARM or PowerShell creation, not the portal rule-creation UI. Preserve existing network rules.
• Verify the ADLS DFS endpoint, such as https://youraccount.dfs.core.windows.net, and the actual connection principal. Workspace identity enabling a trusted network path does not automatically authorize a different connection identity.

Sources: connection management; workspace identity; trusted workspace access. S3 and other external sources need their own connector’s authorization/network checks; ADLS role names do not apply.

Back to symptom choices · Verify this fix

D. Preview fails, or the query returns no rows

A query succeeding in one tool does not make another error a UI false positive. Compare the same target, principal, operation and policy context.

A shortcut under Files is not automatically a SQL table. A successful metadata/list operation is weaker evidence than an actual data read.

3. Prove the fix worked

Use the smallest approved read. These snippets are read-only, but still run workloads and may reveal data. Replace placeholders with an authorized test table/column and confirm the execution identity. They were not executed in a Fabric tenant for this article.

-- Consumer SQL analytics endpoint; replace all names.
-- Choose a non-sensitive column approved by the table owner.
SELECT TOP (10) [YourApprovedTestColumn]
FROM [YourSchema].[YourShortcutTable];

# Fabric PySpark notebook; attach the consumer Lakehouse.
# Replace with the actual relative path and an approved column.
shortcut_path = "Tables/YourSchema/YourShortcut"
approved_column = "YourApprovedTestColumn"

df = spark.read.format("delta").load(shortcut_path)
display(df.select(approved_column).limit(10))

Completion checklist

Local checklist only: ticks are not saved between page loads.

Stop condition: the intended user can perform the required operation, unintended access remains denied, and no unnecessary grants or disabled protections remain.

4. Still failing? Escalate with useful evidence

After the documented propagation window and a failed retest, stop unrelated changes. OneLake-to-SQL security sync can take up to five minutes. Certain delegated SQL owner-permission changes can remain cached for 30–60 minutes; that is a different mechanism, not a universal wait time for every 403.

Do not pause a production capacity or flip access modes just to clear caches without a change plan. These operations can interrupt workloads; a mode switch can affect SQL objects and security definitions.

Copy this sanitized incident template

Symptom and exact error:
UTC time and request/activity ID:
Consumer workspace/item IDs (private support channel only):
Shortcut path and target type:
Target item/path (redacted if sensitive):
Failing engine and interactive/scheduled context:
Shortcut authentication: passthrough / delegated / unknown
Consumer SQL endpoint mode, if relevant:
Principal type/Object ID (private channel; no credentials):
Same user direct-target read: pass / fail / not tested
Same user shortcut data read: pass / fail / not tested
Expected test visibility and observed result (no sensitive rows):
Recent policy, connection, path or schema change:
Smallest change tried and time:
Rollback performed or planned:

Send this to the workspace/data owner first. If permissions and supported configuration are verified but the issue persists, use your organization’s Microsoft Support process. Never post tokens, SAS URLs, secrets or raw protected rows in a public forum.

Timing and sync reference: Microsoft SQL security troubleshooting.

Common questions

Official references and review scope

Reviewed against Microsoft documentation on 23 October 2026. Product behavior and UI can change; the linked documentation takes precedence. This is an independent guide, not a Microsoft-certified repair procedure. Web checks do not substitute for a test in your tenant.

1. OneLake shortcut security — both-path permissions, authentication models and engine exceptions.
2. OneLake shortcuts — supported layouts, engines and read examples.
3. OneLake security for SQL endpoints — access modes, mapping and mode-change impact.
4. SQL security troubleshooting — secured shortcut sources, synchronization and caching.
5. Manage shortcut connections — inspect and replace shared connections.
6. Authenticate with workspace identity — supported ADLS connection pattern and required scope.
7. Trusted workspace access — F capacity, identity, authorization and network rules.
8. OneLake data access control model — workspace, item and data-role interaction.