# When Does Magika Return Generic Labels Like "Unknown Binary Data"

> Discover when Magika returns generic labels like Unknown Binary Data. Learn about confidence scores, file size limits, and binary-versus-text heuristics for accurate file identification.

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

---

**Magika returns generic labels such as "Unknown binary data" or "Generic text document" whenever the neural network's confidence score falls below per-content-type thresholds or when files are too small to process, defaulting to binary-versus-text heuristics.**

In the `google/magika` repository, the content-type detection system relies on deep learning models with specific confidence requirements. When the model cannot provide a trustworthy prediction, Magika intentionally returns generic labels rather than guessing specific formats. Understanding **when Magika returns generic labels** helps developers interpret results and handle edge cases in file processing pipelines.

## How Magika Decides Between Specific and Generic Labels

The core decision logic resides in [`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py). Specifically, the `_get_output_label_from_dl_label_and_score` method (lines 998‑1026) evaluates whether to trust the model's raw prediction. When the confidence is insufficient, the code falls back to either `ContentTypeLabel.TXT` for text files or `ContentTypeLabel.UNKNOWN` for binary files, returning the human-readable descriptions "Generic text document" or "Unknown binary data" respectively.

This fallback occurs when the model's score fails to meet two possible criteria:

- **The per-content-type high-confidence threshold** (e.g., `0.9` for most types, `0.95` for `unknown`)
- **The global medium-confidence threshold** (typically `0.5` as defined in [`config.min.json`](https://github.com/google/magika/blob/main/config.min.json))

If the score falls below both thresholds, Magika discards the specific prediction and assigns a generic label based solely on the file's binary versus text nature.

## Three Scenarios That Trigger Generic Label Fallbacks

### Low Confidence Scores Below Per-Content-Type Thresholds

Each content type in the `standard_v3_3` model (defined in [`assets/models/standard_v3_3/config.min.json`](https://github.com/google/magika/blob/main/assets/models/standard_v3_3/config.min.json)) maintains its own high-confidence threshold. For example, `crt` and `handlebars` require scores above `0.9`, while the `unknown` label itself requires `0.95`. If the model outputs a prediction with a confidence of `0.4` for a PE32 executable, Magika compares this against the type-specific threshold. When the score is insufficient, the code in [`magika.py`](https://github.com/google/magika/blob/main/magika.py) triggers the generic fallback logic instead of returning the uncertain label.

### Files Smaller Than the Minimum Ingest Size

Magika's neural network requires a minimum input size of approximately **8 bytes**. Files smaller than this threshold never reach the model. Instead, Magika applies a lightweight heuristic to determine if the content appears textual or binary, then immediately returns the corresponding generic label. This behavior is documented in [`website-ng/src/content/docs/core-concepts/how-magika-works.md`](https://github.com/google/magika/blob/main/website-ng/src/content/docs/core-concepts/how-magika-works.md) and implemented in the same fallback path as low-confidence predictions.

### Explicit Label Overrides That Fail Validation

The model configuration supports an `overwrite_map` (referenced in [`magika.py`](https://github.com/google/magika/blob/main/magika.py) lines 84‑90) that can remap raw predictions to different output labels. If the code applies an override from `self._model_config.overwrite_map` but the resulting label still fails the confidence checks described above, Magika applies the generic label fallback. This ensures that remapped but uncertain predictions do not bypass the safety mechanisms.

## Confidence Threshold Configuration in Magika

The thresholds governing these decisions are stored in each model's [`config.min.json`](https://github.com/google/magika/blob/main/config.min.json). For the default **standard_v3_3** model, the configuration specifies:

```json
{
  "thresholds": {
    "crt": 0.9,
    "handlebars": 0.9,
    "unknown": 0.95
  },
  "medium_confidence_threshold": 0.5
}

```

When `magika.identify()` processes a file, it compares the raw model score against the specific threshold for the predicted content type. If the score is below that threshold, it checks against the global `medium_confidence_threshold`. Failure to exceed either results in the generic label assignment through the logic in `_get_output_label_from_dl_label_and_score`.

## Practical Examples: Generating Generic Labels

The following examples demonstrate how to trigger Magika's generic label returns using the Python API and CLI.

### Python API with Low-Confidence Random Bytes

```python
from magika import Magika

magika = Magika(prediction_mode="high-confidence")

# Random binary content that confuses the model

result = magika.identify(b"\x00\xff\xab\xcd\x12\x34")
print(result.prediction.output.label)        # → unknown

print(result.prediction.output.description)  # → Unknown binary data

```

*Why this happens*: The raw model score for the nearest content type remains below the per-type high-confidence threshold (`0.95` for `unknown`), forcing the fallback to `ContentTypeLabel.UNKNOWN`.

### CLI with Tiny Text Files

```bash
$ echo -n "a" > tiny.txt    # Creates a 1-byte file

$ magika tiny.txt
tiny.txt: Generic text document

```

The file size is below the model's minimum ingest size, so Magika skips inference and returns the generic text label based on character analysis.

### CLI with Unrecognizable Binary Data

```bash
$ head -c 1024 /dev/urandom > random.bin
$ magika random.bin
random.bin: Unknown binary data

```

Despite sufficient file size, the random bytes produce no confident predictions. The model's highest score falls below the required thresholds, triggering the generic binary fallback.

## Summary

- **Magika returns generic labels** whenever model confidence is insufficient to trust a specific content-type prediction.
- The decision occurs in [`python/src/magika/magika.py`](https://github.com/google/magika/blob/main/python/src/magika/magika.py) within the `_get_output_label_from_dl_label_and_score` method, which compares scores against per-type thresholds and a global medium-confidence threshold.
- **Three main conditions** trigger this behavior: scores below content-type thresholds, files smaller than ~8 bytes, and remapped labels that fail validation.
- The thresholds are configurable per model in [`config.min.json`](https://github.com/google/magika/blob/main/config.min.json), with the default `standard_v3_3` model using values ranging from `0.9` to `0.95` for high confidence and `0.5` for medium confidence.
- Generic outputs are **either** "Unknown binary data" for binary content or "Generic text document" for text content, never specific format identifications.

## Frequently Asked Questions

### What is the difference between "Unknown binary data" and "Generic text document"?

"Unknown binary data" (`unknown`) indicates that Magika detected binary content but could not identify a specific format with sufficient confidence. "Generic text document" (`txt`) indicates the content appears to be text, but Magika cannot determine a specific text-based format like HTML or JavaScript. The distinction is made by analyzing whether the bytes contain primarily text characters or binary data.

### Can I adjust the confidence thresholds to reduce generic label returns?

Yes, you can modify the `thresholds` and `medium_confidence_threshold` values in the model's [`config.min.json`](https://github.com/google/magika/blob/main/config.min.json) file, located at [`assets/models/standard_v3_3/config.min.json`](https://github.com/google/magika/blob/main/assets/models/standard_v3_3/config.min.json) for the default model. Lowering these values causes Magika to accept lower-confidence predictions, though this increases the risk of misclassification. Alternatively, instantiate `Magika(prediction_mode="medium-confidence")` to use less strict default thresholds without editing configuration files.

### Why does Magika return generic labels instead of its best guess?

According to the source code in `google/magika`, the system prioritizes reliability over specificity. When the model's confidence score falls below the thresholds defined in `_get_output_label_from_dl_label_and_score`, returning a specific but potentially incorrect label would be less useful than indicating "unknown." This design prevents downstream tools from processing files based on incorrect format assumptions while still providing useful binary-versus-text categorization.

### What file size triggers the generic label fallback?

Files smaller than approximately **8 bytes** automatically receive generic labels because they fall below the model's minimum ingest size. For these tiny files, Magika never invokes the neural network; instead, it applies a simple heuristic to distinguish text from binary and returns the appropriate generic label immediately.