{"record":{"id":"f20d4e49698d0096","repo":"headroomlabs-ai/headroom","slug":"magika-is-required-for-ml-based-content-detection","errorCode":null,"errorMessage":"Magika is required for ML-based content detection. Install with: pip install magika","messagePattern":"Magika is required for ML-based content detection\\. Install with: pip install magika","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/compression/detector.py","lineNumber":141,"sourceCode":"        \"org\",\n    }\n)\n\n\ndef _get_magika() -> Magika:\n    \"\"\"Get or create the singleton Magika instance.\n\n    Lazy-loads on first use to avoid import cost if not needed.\n    \"\"\"\n    global _magika_instance\n    if _magika_instance is None:\n        try:\n            from magika import Magika\n\n            _magika_instance = Magika()\n            logger.debug(\"Magika model loaded successfully\")\n        except ImportError as e:\n            raise ImportError(\n                \"Magika is required for ML-based content detection. \"\n                \"Install with: pip install magika\"\n            ) from e\n    return _magika_instance\n\n\ndef _magika_available() -> bool:\n    \"\"\"Check if Magika is available without loading it.\"\"\"\n    try:\n        import magika  # noqa: F401\n\n        return True\n    except ImportError:\n        return False\n\n\nclass MagikaDetector:\n    \"\"\"ML-based content type detector using Google's Magika.","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/compression/detector.py#L123-L159","documentation":"Raised from the lazy Magika singleton loader in headroom.compression.detector when `from magika import Magika` raises ImportError. Magika is the ML-based content-type detector used to classify file contents; it is an optional dependency, so it is only imported on first use and the failure surfaces as an ImportError with install instructions chained from the original error. A companion _magika_available() helper exists so callers can probe availability without triggering the load.","triggerScenarios":"Any code path that first requests the Magika singleton (content detection on compression candidate files) in an environment where the `magika` package is not installed, is installed in a different interpreter, or fails to import (e.g. missing model assets on old magika versions).","commonSituations":"headroom installed without the optional ML extra; running under a different Python than the one where magika was pip-installed; slim Docker images that trimmed optional deps; air-gapped environments where magika's model download at Magika() construction was blocked (note: that would raise a different error, but import-time failures land here too).","solutions":["Install magika into the same interpreter headroom uses: `pip install magika`","If it should already be installed, check `python -c \"import magika\"` in that exact environment and fix the interpreter/venv mismatch","If ML detection is optional for your flow, gate the feature with headroom's `_magika_available()` probe (or a try/except around the detector call) instead of letting the ImportError propagate"],"exampleFix":"# before\nfrom headroom.compression.detector import _get_magika\nmagika = _get_magika()  # ImportError: Magika is required...\n\n# after\n# pip install magika\nfrom headroom.compression.detector import _get_magika\nmagika = _get_magika()  # loads model on first call","handlingStrategy":"try-catch","validationCode":"from headroom.compression.detector import _magika_available\n\nif not _magika_available():\n    print(\"magika not installed — ML content detection disabled; `pip install magika` to enable\")","typeGuard":null,"tryCatchPattern":"try:\n    from headroom.compression.detector import _get_magika\n    magika = _get_magika()\nexcept ImportError as e:\n    logger.warning(\"ML detection unavailable (%s); falling back to heuristic detection\", e)\n    magika = None","preventionTips":["Declare magika in your deployment environment when ML detection is required","Use _magika_available() to feature-probe instead of catching the load-time ImportError","Run import smoke-tests (`python -c 'import magika'`) in CI for the exact interpreter"],"tags":["dependency","import","ml","content-detection","python"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}