Introduction

TreeExplainer expects the SHAP values for one prediction to add up to the model output, up to numerical tolerance. When the additivity check fails, it usually means the explainer is not looking at the model and feature representation in exactly the way the model was trained, or that you are comparing a different output space than the explainer expects.

What the Additivity Check Is Verifying

For a tree model, SHAP aims to satisfy:

expected_value + sum(feature_contributions) = model_output

If that identity does not hold closely enough, SHAP raises an exception instead of returning values that look authoritative but are inconsistent with the prediction being explained.

That is a good guardrail. The failure is telling you that something about the explanation path does not line up.

Common Reasons It Fails

The most common causes are:

• feature columns are in a different order than the model saw during training
• preprocessing was applied during training but not during explanation, or vice versa
• you are explaining probabilities while the explainer is reasoning about raw tree outputs
• the model is wrapped in a pipeline or custom object that SHAP does not interpret the way you expect
• numerical differences are large enough to break the strict check

In practice, feature mismatch is the most common real bug.

Start by Verifying the Exact Input Matrix

If the model was trained on transformed features, explain that same transformed matrix, not the original raw DataFrame.

For example:

1import shap
2
3X_train_transformed = preprocessor.transform(X_train)
4X_test_transformed = preprocessor.transform(X_test)
5
6model.fit(X_train_transformed, y_train)
7
8explainer = shap.TreeExplainer(model)
9shap_values = explainer.shap_values(X_test_transformed)

If you instead pass raw X_test into an explainer built around a model trained on encoded or scaled features, the additivity check is likely to fail because the model output you are comparing against is not based on the same feature space.

Be Careful About Output Space

For classification, tree models often have several meaningful outputs:

• raw margin or logit
• probability
• class label

SHAP explanations are sensitive to which one you ask for. If the model output you compare against is probability, but the explainer is working in raw margin space, the additivity check can look wrong even though the model itself is fine.

A safer pattern is to be explicit:

explainer = shap.TreeExplainer(model, model_output="raw")

Then compare SHAP sums against the model's raw output, not against a probability that came from an extra transformation layer.

Pipelines and Wrappers Need Extra Attention

A scikit-learn pipeline can hide the distinction between:

• raw business features
• transformed numeric matrix
• final tree model

That is convenient for training, but it can make explanation debugging confusing. If SHAP fails on the pipeline object, try isolating the actual tree estimator and the exact transformed matrix it consumes.

That debugging step often answers the question immediately: the issue is not TreeExplainer itself, but a mismatch between the wrapped pipeline and the explainer's assumptions.

Only Disable the Check After Validation

You can turn off the additivity assertion:

explanation = explainer(X_test_transformed[:10], check_additivity=False)

But this should be the last step, not the first. It is appropriate only after you have already validated that:

• feature ordering is correct
• preprocessing is correct
• the model output space is the one you intended

Otherwise you are just suppressing a useful warning.

A Practical Debugging Sequence

Use this order:

1. confirm the model is truly tree-based and supported by TreeExplainer
2. confirm the feature columns and order exactly match training
3. confirm you are explaining the same transformed data the model consumes
4. confirm whether you want raw output or probability space
5. try check_additivity=False only after the earlier checks pass

This is faster than randomly changing SHAP options because it follows the real failure modes.

Numerical Tolerance Is Not the Main Story

People often assume the exception is "just floating-point noise." Small numerical differences do happen, but large additivity failures usually signal a representation mismatch, not ordinary rounding.

That is why the fix is usually not "ignore it." The fix is usually to align:

• model
• feature matrix
• output interpretation

Once those three match, the error often disappears.

Common Pitfalls

• Explaining raw features when the model was trained on encoded or transformed features.
• Comparing SHAP sums against probabilities when the explainer is using raw model output.
• Passing a complex pipeline wrapper to TreeExplainer without checking what the inner tree model actually sees.
• Disabling check_additivity before verifying the feature representation.
• Assuming every failure is harmless floating-point noise.

Summary

• TreeExplainer expects SHAP values to add up to the model output it is explaining.
• Additivity failures usually come from mismatched feature representations or output spaces.
• Always explain the exact matrix the tree model consumes.
• Be explicit about whether you are working in raw output or probability space.
• Disable the check only after you have validated that the explanation setup is correct.