# What Does the overwrite_reason Field in Magika Results Indicate?

> Understand the overwrite_reason field in Magika results. Learn why Magika's content-type output may differ from the raw model prediction due to configuration or low confidence.

- Repository: [Google/magika](https://github.com/google/magika)
- Tags: api-reference
- Published: 2026-04-16

---

**The `overwrite_reason` field indicates why Magika's final content-type output differs from the raw deep-learning model's prediction, using an enum to distinguish between no change, configuration-based overwrites, or low-confidence fallbacks.**

The `overwrite_reason` field is a critical component of the results returned by the `google/magika` content-type detection library. As implemented in the Python, Rust, and JavaScript bindings, this field provides transparency into the post-processing pipeline that transforms raw model outputs into final predictions. Understanding this field helps developers debug classification results and implement conditional logic based on why a specific label was selected.

## Understanding the overwrite_reason Field

The **`overwrite_reason`** is part of the **`MagikaPrediction`** dataclass that accompanies every Magika result. It tells the caller why the final output content-type (`prediction.output`) differs from the raw deep-learning model's prediction (`prediction.dl`), or why it remains identical. This field is essential for debugging systematic misclassifications and understanding when confidence thresholds have triggered fallbacks.

### The OverwriteReason Enum Values

The field is an instance of the **`OverwriteReason`** enum defined in [`magika/types/overwrite_reason.py`](https://github.com/google/magika/blob/main/magika/types/overwrite_reason.py). The enum provides three possible values:

- **`OverwriteReason.NONE`** — No post-processing was applied. The final output label matches exactly what the deep-learning model predicted.
- **`OverwriteReason.OVERWRITE_MAP`** — The model's label was replaced according to the **overwrite map** shipped with the model configuration. This map corrects systematic mis-classifications, such as remapping generic `application/*` labels to more specific content types.
- **`OverwriteReason.LOW_CONFIDENCE`** — The model's confidence score fell below the threshold for the selected **prediction mode** (high, medium, or best-guess). Magika falls back to a generic label (`TXT` or `UNKNOWN`). If this fallback happens to equal the original model label, the reason is downgraded to `NONE`.

### The Internal Logic Flow

The logic that sets this field lives in **`_get_output_label_from_dl_label_and_score`** within [`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py) (around lines 78–90), with mirrored implementations in the Rust and JavaScript bindings. The pipeline follows these steps:

1. **Apply the overwrite map** — If the configuration map changes the label, `overwrite_reason` becomes `OVERWRITE_MAP`.
2. **Check confidence thresholds** — Depending on the `prediction_mode`, the score may be high enough to retain the (possibly overwritten) label.
3. **Force generic fallback** — If confidence is insufficient, the result is forced to `TXT` or `UNKNOWN`, and `overwrite_reason` is set to `LOW_CONFIDENCE`.
4. **Validate necessity** — If the forced generic label equals the original DL label, the reason resets to `NONE` because no actual overwrite occurred.

## Code Examples for Checking overwrite_reason

You can inspect the `overwrite_reason` field programmatically across all supported languages to build conditional processing logic.

### Python Implementation

When using the Python API, access the field directly from the prediction object:

```python
from magika import Magika
from magika.types import OverwriteReason

magika = Magika(prediction_mode="HIGH_CONFIDENCE")
result = magika.identify_path("example.pdf")

print("DL label:", result.prediction.dl.label)
print("Output label:", result.prediction.output.label)
print("Overwrite reason:", result.prediction.overwrite_reason)

# Typical output:

# DL label: application/pdf

# Output label: application/pdf

# Overwrite reason: OverwriteReason.NONE

```

If the file triggers an overwrite map entry, the reason reflects the configuration change:

```python
magika = Magika()
result = magika.identify_path("some_binary")
print(result.prediction.overwrite_reason)

# → OverwriteReason.OVERWRITE_MAP

```

### JavaScript and Rust Usage

The JavaScript implementation exposes the enum as lowercase strings:

```javascript
import { Magika } from "magika";

(async () => {
  const magika = new Magika();
  const { prediction } = await magika.identifyPath("example.bin");
  console.log("Reason:", prediction.overwrite_reason); 
  // Outputs: "none", "overwrite_map", or "low_confidence"
})();

```

In Rust, the field is accessible after obtaining a result:

```rust
use magika::magika::Magika;

let magika = Magika::new().unwrap();
let result = magika.identify_path("example.txt").unwrap();

println!("Reason: {}", result.prediction.overwrite_reason);

```

## Key Source Files and Functions

Understanding `overwrite_reason` requires familiarity with these specific files in the `google/magika` repository:

- **[`python/src/magika/types/overwrite_reason.py`](https://github.com/google/magika/blob/main/python/src/magika/types/overwrite_reason.py)** — Defines the `OverwriteReason` enum used across all language bindings.
- **[`python/src/magika/types/magika_prediction.py`](https://github.com/google/magika/blob/main/python/src/magika/types/magika_prediction.py)** — Contains the `MagikaPrediction` dataclass that stores the DL prediction, final output, and overwrite reason.
- **[`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py)** — Implements `_get_output_label_from_dl_label_and_score`, the core function that determines when and why to overwrite predictions.
- **[`js/src/overwrite-reason.ts`](https://github.com/google/magika/blob/main/js/src/overwrite-reason.ts)** — JavaScript/TypeScript enum mirroring the Python implementation.
- **[`rust/lib/src/model.rs`](https://github.com/google/magika/blob/main/rust/lib/src/model.rs)** — Rust representation of the overwrite map and the logic that yields an `OverwriteReason`.

## Summary

- The **`overwrite_reason`** field explains deviations between raw model predictions and final output labels in Magika results.
- Valid values are **`NONE`**, **`OVERWRITE_MAP`**, and **`LOW_CONFIDENCE`**, defined in [`magika/types/overwrite_reason.py`](https://github.com/google/magika/blob/main/magika/types/overwrite_reason.py).
- **`OVERWRITE_MAP`** indicates the model's prediction was replaced via the configuration's overwrite map to correct systematic errors.
- **`LOW_CONFIDENCE`** triggers when prediction scores fall below mode-specific thresholds, forcing fallback to `TXT` or `UNKNOWN`.
- The logic resides in **`_get_output_label_from_dl_label_and_score`** within the Python implementation and is mirrored in Rust and JavaScript bindings.

## Frequently Asked Questions

### What is the difference between the dl and output fields in Magika results?

The **`dl`** field contains the raw label and confidence score produced by the deep-learning model before any post-processing. The **`output`** field contains the final content-type label after applying the overwrite map and confidence threshold checks. The `overwrite_reason` field specifically tracks why these two values might differ.

### When does Magika use the LOW_CONFIDENCE overwrite reason?

Magika sets **`LOW_CONFIDENCE`** when the model's confidence score falls below the threshold defined by the current **prediction mode** (high, medium, or best-guess). In this case, the system disregards the model's prediction and falls back to a generic `TXT` or `UNKNOWN` label to avoid false positives.

### How can I disable the overwrite map in Magika?

You cannot directly disable the overwrite map through the public API, as it is baked into the model configuration files (such as [`config.min.json`](https://github.com/google/magika/blob/main/config.min.json)). However, you can compare `result.prediction.dl.label` with `result.prediction.output.label` and ignore the overwrite logic by using the raw DL prediction when `overwrite_reason` equals `OVERWRITE_MAP`.

### Is overwrite_reason available in all Magika language bindings?

Yes, the `overwrite_reason` field is available in the **Python**, **JavaScript/TypeScript**, and **Rust** implementations of Magika. While the Python API uses the `OverwriteReason` enum class, the JavaScript and Rust versions expose the values as strings (`"none"`, `"overwrite_map"`, `"low_confidence"`), ensuring consistent behavior across platforms.