How do I fix a Delta protocol-version mismatch?

Summary

• A Delta protocol-version mismatch means a table's protocol asks for reader or writer support that your Delta Lake client doesn't have. The errors are DELTA_INVALID_PROTOCOL_VERSION and DELTA_UNSUPPORTED_FEATURES_FOR_READ or DELTA_UNSUPPORTED_FEATURES_FOR_WRITE, and the message names the versions or table features involved.
• The default fix is to upgrade the failing client. Delta Lake features are backward compatible, so a newer client can always read and write a table written by an older one.
• If you can't upgrade the client, remove the feature with ALTER TABLE <table> DROP FEATURE <feature>, available in Delta Lake 4.0.0 and above for a fixed list of features such as deletionVectors and columnMapping.
• Don't lower delta.minReaderVersion or delta.minWriterVersion by hand. Delta's docs call protocol upgrades irreversible, and dropping a feature is the supported way down.

How do I fix a Delta protocol-version mismatch?

Upgrade the Delta Lake client that's failing, because the table's protocol requires features that client doesn't implement. If you can't upgrade it, remove the feature that raised the requirement with ALTER TABLE <table> DROP FEATURE <feature>, which Delta Lake supports from 4.0.0 for a fixed list of features. Don't edit the protocol version properties down by hand: upgrades are irreversible except by dropping a feature.

What is a Delta protocol version?

Every Delta table records a protocol in its transaction log: minReaderVersion and minWriterVersion, plus a readerFeatures list when the reader version is 3 and a writerFeatures list when the writer version is 7. A client can read a table only if it supports the read protocol. Writers must satisfy both the reader and writer protocols, because every writer has to construct a snapshot of the table first.
Mismatches run one way. Delta Lake features are backward compatible, so a newer client always handles an older table. The trouble starts when a newer engine enables a feature, such as deletion vectors (writer version 7, reader version 3), and an older client opens the table.

Diagnose the mismatch

The error says what's missing. DELTA_INVALID_PROTOCOL_VERSION reports the reader and writer versions the table requires and the versions your Delta Lake release supports. DELTA_UNSUPPORTED_FEATURES_FOR_READ and DELTA_UNSUPPORTED_FEATURES_FOR_WRITE list the table features your client doesn't support. To see the table's current protocol from any up-to-date client:

from delta.tables import DeltaTable

detail = DeltaTable.forPath(spark, "/data/events").detail()
detail.select("minReaderVersion", "minWriterVersion").show()

In SQL, DESCRIBE DETAIL events returns the same columns.

Symptom	Likely cause	Fix
DELTA_INVALID_PROTOCOL_VERSION with required reader and writer versions	The table's protocol is newer than your Delta Lake release	Upgrade the client to a release that supports those versions
DELTA_UNSUPPORTED_FEATURES_FOR_READ listing a feature such as deletionVectors	A reader table feature your client doesn't implement	Upgrade the client, or drop the feature if it's on the droppable list
DELTA_UNSUPPORTED_FEATURES_FOR_WRITE	A writer feature your client can't honor	Upgrade the writers; older clients can often still read
Old jobs fail right after someone enabled a feature	Enabling the feature upgraded the protocol automatically	Upgrade those jobs, or drop the feature; turning it off doesn't downgrade the protocol
Lowering delta.minReaderVersion by hand fails or changes nothing	Protocol versions can't be lowered through properties	Use DROP FEATURE

Fix it: upgrade, or drop the feature

Upgrade the client. Pick the Delta Lake release that matches your Spark line. Delta's compatibility table pairs Delta Lake 4.0.x with Spark 4.0.x, lists Spark 4.0.x and 4.1.x for Delta Lake 4.1.x through 4.3.x, and Spark 3.5.x for Delta Lake 3.x. The feature table gives the minimum Delta version per feature: 2.3.0 for deletion vectors, 3.1.0 for clustering, 4.0.0 for the Variant type.
Drop the feature. Delta Lake 4.0.0 and above can drop deletionVectors, typeWidening-preview, typeWidening, v2Checkpoint, columnMapping, vacuumProtocolCheck, checkConstraints, inCommitTimestamp and checkpointProtection. No other feature can be dropped.

ALTER TABLE events DROP FEATURE deletionVectors;

Delta disables the feature's properties, rewrites data files to remove its traces, writes protected checkpoints, adds the checkpointProtection writer feature, and downgrades the protocol to the lowest versions that support what's left. Readers that lacked the dropped feature can then open the table, as long as they support everything that remains. If an older writer can't handle checkpointProtection, run ALTER TABLE events DROP FEATURE deletionVectors TRUNCATE HISTORY twice, at least 24 hours apart. It removes table history older than 24 hours, so test plain DROP FEATURE first.
To prevent a repeat, enable features table by table and only after every reader and writer of that table supports them. The Delta docs recommend the lowest protocol versions that support the features a table needs.

How Databricks approaches Delta protocols

On Databricks, features are enabled through SQL syntax or table properties, and some pull in others: CLUSTER BY in CREATE TABLE enables liquid clustering, which in turn enables V2 checkpoints. If tables are only used through Databricks, the docs say tracking minimum Databricks Runtime versions is enough. If external Delta clients read or write them, verify those clients support a feature before you turn it on. Databricks supports the same DROP FEATURE command and recommends never altering minReaderVersion or minWriterVersion directly. See Delta Lake feature compatibility and protocols.

FAQs

Can I set delta.minReaderVersion back to a lower number?

No. Delta's docs call protocol version upgrades irreversible, and Databricks notes that setting these properties to a lower value doesn't downgrade the table. Drop the feature instead.

Does a newer Delta client ever break an older table?

Not by reading or writing it. Tables written by a lower Delta Lake version can always be read and written by a higher one. The protocol changes when a feature is enabled on the table, which is the moment older clients can start failing.

Do other engines follow the same rules?

Yes, through their Delta connectors. A client that doesn't understand a feature listed in the table's protocol can't read or write that table, so check each connector's supported features before enabling new ones on shared tables.