Fix missing or stale Lakehouse tables in the Fabric SQL endpoint

A Delta table can be queryable in Spark and still be absent or stale in the SQL analytics endpoint. The first question is not “which refresh button is broken?” It is “is this a managed Delta table under Tables?”

Files and tables are different:

• Files can contain supported file layouts.
• The SQL analytics endpoint discovers Delta tables under the Lakehouse Tables area.

Parquet files under Files do not become SQL tables automatically.

The validation workspace was blog_lakehouse_troubleshooting, with a sales_lakehouse and its SQL analytics endpoint on trial capacity.

Use this order

1. Confirm the object is a Delta table under Tables.
2. Query it in Spark.
3. Inspect the SQL analytics endpoint.
4. Trigger a supported metadata refresh.
5. Check compatibility, locks, and synchronization delay.

1. Prove the table exists

Attach the Lakehouse to a notebook:

spark.sql("SHOW TABLES").show(truncate=False)
spark.table("sales_orders").limit(10).show()

Inspect the table:

spark.sql("DESCRIBE DETAIL sales_orders").show(truncate=False)

If spark.table("sales_orders") fails, this is not yet an endpoint-sync problem. Fix the registration or write a managed Delta table:

orders_df.write \
    .format("delta") \
    .mode("overwrite") \
    .saveAsTable("sales_orders")

Do not use MSCK REPAIR TABLE as a generic Fabric metadata repair. It belongs to partition-discovery patterns and does not repair an absent or invalid Delta table.

2. Refresh the endpoint

Open the Lakehouse’s SQL analytics endpoint:

1. Select Query SQL analytics endpoint.
2. In Explorer, select Refresh.
3. Wait for synchronization to finish.
4. Reopen or refresh the Tables node.

Then query:

select top (10) *
from dbo.sales_orders;

Fabric normally synchronizes automatically. Manual refresh is useful when a schema change matters before the background process catches up.

3. Refresh one table

For SQL analytics endpoints created after enabling New metadata sync (preview):

exec sys.sp_dw_refresh_ext_table 'dbo.sales_orders';

Use this for a specific table. For added or removed tables and columns, use the portal refresh or the documented REST API.

4. Inspect synchronization

With New metadata sync enabled:

select
    object_id,
    last_update_time_utc,
    latest_log_version,
    latest_checkpoint_version,
    is_blocked
from sys.dm_db_external_tables_log_status;

last_update_time_utc shows the latest successful update, latest_log_version shows the processed Delta log position, and is_blocked = 1 indicates the last update was blocked.

5. Make refresh part of a pipeline

If downstream queries must see the result of an ingestion job:

1. finish ingestion and transformation;
2. add one Refresh SQL analytics endpoint activity;
3. select the workspace and endpoint ID; and
4. start semantic-model refresh or downstream queries only after it succeeds.

One refresh at the end is safer than several refreshes between writes. Active writers can hold locks and make refresh fail intermittently.

Common causes

The data is under Files

Read the files with Spark and write a managed Delta table to Tables.

Delta features are unsupported

Check the SQL analytics endpoint’s Delta and data-type limitations. New metadata sync does not support deprecated multi-part checkpoints.

Workspace discovery is busy

Metadata discovery is workspace-level. Many Lakehouses can increase latency.

A writer still holds a lock

Finish notebooks or pipelines that write the table, then refresh once.

The client cached the schema

Refresh the endpoint, then reconnect or refresh metadata in the query tool.

Recovery sequence

Do not start by dropping the table:

1. validate it in Spark;
2. refresh the endpoint;
3. refresh the individual table when supported;
4. inspect the status DMV;
5. verify Delta compatibility and locks; and
6. recreate the Spark table only if registration or storage is actually invalid.

Sources

• SQL analytics endpoint metadata sync
• Refresh SQL analytics endpoint pipeline activity

The useful distinction is simple: prove the table first, then use Fabric’s supported refresh controls. Treating every delay as corruption creates a second problem.