This page maps the concrete failures you are most likely to hit — symptom → cause → fix. It quotes exact OpenMed-owned error strings and gives the command or configuration change for each case; wrapped operating-system, network, and third-party errors can vary. If your problem is conceptual rather than an error, start with the FAQ; if you are setting up for the first time, see the Quick Start and Configuration & Validation.
!!! tip "Run the built-in doctor first"
Before digging in, run the offline environment check. It reports your Python version and architecture,
which selected runtime extras are importable, whether an HF_TOKEN is present, and whether offline mode
is active. Dependency, token, Python-version, and architecture checks that need action include a
remediation Hint:.
```bash
openmed doctor # human-readable check list
openmed doctor --json # machine-readable; non-zero exit on any FAIL
```
Abridged sample output:
```text
PASS python_version: 3.11.9
PASS python_arch: arm64
WARN hf: transformers not installed
Hint: Install with: pip install transformers
PASS openmed_offline: 0
```
openmed doctor --json includes the same checks returned by
openmed.core.doctor.clinical_brief_readiness(). This reusable function inspects
platform metadata, package specs and local cache metadata only: it does not
import MLX, construct models, download artifacts or call an inference backend.
Every new check has a controlled code, a PASS/WARN status and a remediation
hint when needed. These checks do not include private paths, filenames or tokens.
brief_extractive: explicit deterministic extractive mode is available without MLX.brief_mlx_platform: the built-in MLX alias requires Apple silicon on macOS.brief_mlx_runtime: the MLX, MLX-LM and Hub packages are discoverable.brief_summarizer_cache: the registered pinned Maple revision has non-empty config/tokenizer files and weights (all indexed shards when sharded) in the distribution cache. This inventory does not satisfy runtime admission.brief_summarizer_package: the application has registered a local package with a trusted immutable manifest pin. Registration does not verify files; the runtime still verifies its complete provisioned package before loading. The default remains a warning until the host registers a reviewed package.brief_raw_note_pii_cache: the default English PII artifact is cached. Its localmainreference must resolve to a complete snapshot; this is not an immutable pin or verification of another language/model chosen by the caller.brief_nli_provider: a released NLI checkpoint is registered, or the controlled warningcaller_nli_provider_requiredexplains the caller-supplied option.
PASS means the named prerequisite was observed, not that inference succeeded
or that a model is clinically qualified. The checks do not validate cache or
provisioned package contents as model code, calibration quality, a review packet,
or sufficient device memory. Cache index reads are bounded to 1 MiB; malformed
or deeply nested indexes are reported as missing without parser diagnostics.
Supply a reviewed context and a calibrated local NLI provider to compose a brief;
training a new model is optional and is not a release requirement.
Warnings alone keep the doctor exit code at zero. A failed diagnostic emits
outcome: "check_failed" and exits 1; see the
machine contract for scripting semantics.
OpenMed ships a small permissive core and keeps heavy or platform-specific stacks behind
optional extras declared in pyproject.toml.
If you call a feature whose extra is not installed, you get an ImportError/ModuleNotFoundError or a
MissingDependencyError (a subclass of ImportError) whose message names the fix.
Symptom. Loading a model or calling analyze_text, extract_pii, or deidentify on a Hub model fails
with a missing transformers import, or you see:
ImportError: HuggingFace transformers is required. Install with: pip install transformers
Cause. The core install does not pull in the Hugging Face runtime. The
Transformers/tokenizers/accelerate stack lives in the hf extra. The extra
does not choose a PyTorch build for you; install the CPU, CUDA, or MPS build
that matches your platform separately.
Fix.
pip install "openmed[hf]"Symptom. Backend auto-detection cannot find a usable runtime:
RuntimeError: No inference backend available. Install at least one: pip install openmed[hf] or pip install openmed[mlx]
Related backend errors:
ValueError: Unknown backend 'xyz'. Available: ['hf', 'mlx']— you passed abackend=value that is not"hf"or"mlx".RuntimeError: Backend 'mlx' is not available. Install its dependencies first.— you selected a backend explicitly but its dependencies are not importable on this machine.
Cause. No inference backend is importable. hf is the portable backend
after a compatible PyTorch runtime is installed; mlx is the Apple-Silicon
path.
Fix. Install at least one backend. For hf, first follow the PyTorch
installation instructions for your CPU/GPU platform, then install the OpenMed
extra:
pip install "openmed[hf]" # portable PyTorch/Transformers backend
pip install "openmed[mlx]" # Apple Silicon MLX backendSymptom. A capability-specific call fails with a message shaped like:
Optional dependency 'pdfplumber' is required for this operation. Install with: pip install "openmed[multimodal]".
Cause. OpenMed defers document/image intake, zero-shot NER, framework bridges, exporters, and connectors to purpose-built extras. Dependency errors include a remediation hint; the package-install commands below work from a published OpenMed installation.
Fix. Install the extra the message names. Common ones:
| Feature | Extra | Install command |
|---|---|---|
Document / image intake + OCR (pdfplumber, python-docx, python-pptx, Pillow, DICOM, docTR/Tesseract/EasyOCR) |
multimodal |
pip install "openmed[multimodal]" |
| Outlook MSG ingestion through the isolated GPL-3.0 parser bridge | email-msg-gpl |
pip install "openmed[email-msg-gpl]" |
| Heavier PaddleOCR backend | ocr-paddle |
pip install "openmed[ocr-paddle]" |
| Zero-shot GLiNER NER | gliner |
pip install "openmed[gliner]" |
| GLiNER2.5 entities, classification, relations and decisions | gliner2 |
pip install "openmed[gliner2]" |
| REST service | service |
pip install "openmed[service]" |
| MCP server | mcp |
pip install "openmed[mcp]" |
| Optional Typer/Rich CLI | cli |
pip install "openmed[cli]" |
| Apple Silicon MLX runtime | mlx |
pip install "openmed[mlx]" |
| Core ML packaging | coreml |
pip install "openmed[coreml]" |
| ONNX Runtime | onnx |
pip install "openmed[onnx]" |
| OpenVINO runtime | openvino |
pip install "openmed[openvino]" |
| pandas / polars accessors | pandas / polars |
pip install "openmed[pandas]" / pip install "openmed[polars]" |
| Dask / DuckDB | dask / duckdb |
pip install "openmed[dask]" / pip install "openmed[duckdb]" |
| spaCy component | spacy |
pip install "openmed[spacy]" |
| Presidio bridge | presidio |
pip install "openmed[presidio]" |
| Chinese segmentation, script conversion, and pinyin | zh |
pip install "openmed[zh]" |
| Indic segmentation and transliteration | indic |
pip install "openmed[indic]" |
| Grounding (rapidfuzz) | grounding |
pip install "openmed[grounding]" |
| LangChain / LlamaIndex | langchain / llamaindex |
pip install "openmed[langchain]" / pip install "openmed[llamaindex]" |
| Kafka / cloud object storage | kafka / cloud |
pip install "openmed[kafka]" / pip install "openmed[cloud]" |
Distributed batch shard execution (RayShardExecutor / SparkShardExecutor) |
ray / spark |
pip install "openmed[ray]" / pip install "openmed[spark]" |
| AWQ / GPTQ export | awq / gptq |
pip install "openmed[awq]" / pip install "openmed[gptq]" |
You can stack extras: pip install "openmed[hf,service]" or pip install "openmed[hf,mlx,docs]".
For a combined Chinese and Indic smoke check:
pip install "openmed[zh,indic]"
python -c 'from openmed.interop import indic, zh; assert zh.segment("患者张伟") and indic.segment("रोगी रवि")'Symptom. OCR fails even though openmed[multimodal] is installed, with a message like:
Optional dependency 'tesseract' is required for this operation. Install with: pip install "openmed[multimodal]" and install the system Tesseract binary (e.g. `brew install tesseract` or `apt-get install tesseract-ocr`).
Cause. Tesseract is a system binary that pip does not install. The Python extra provides only the
pytesseract wrapper.
Fix. Install the OS package alongside the extra:
pip install "openmed[multimodal]"
brew install tesseract # macOS
sudo apt-get install tesseract-ocr # Debian/UbuntudocTR and EasyOCR ship inside openmed[multimodal] and need no separate system binary; PaddleOCR lives in
the separate openmed[ocr-paddle] extra.
Symptom. The first call that needs a model fails while resolving files from the Hugging Face Hub:
ValueError: Could not load model OpenMed/…: <underlying Hub / network error>
The wrapped error is whatever transformers/huggingface_hub raised — a connection timeout, an HTTP 401 on
a gated repo, an HTTP 404 for a wrong id, or a proxy/TLS failure.
Cause. OpenMed downloads model artifacts on first use and keeps them in a
local cache. Component-loading paths use OpenMedConfig.cache_dir (default
~/.cache/openmed); direct Hugging Face operations can also use the standard
Hub cache controlled by HF_HOME / HF_HUB_CACHE. OPENMED_CACHE_DIR is read
by selected data and deployment tooling, not as a generic OpenMedConfig
override. Failures are usually network reachability, a proxy, or a
private/gated repo needing a token.
Fix.
-
Behind a proxy / corporate firewall. Export standard proxy variables before the first run:
export HTTPS_PROXY=http://proxy.internal:8080 export HTTP_PROXY=http://proxy.internal:8080
-
Using a Hub mirror. OpenMed honors the standard Hugging Face endpoint variable; point it at your mirror:
export HF_ENDPOINT=https://hf-mirror.example.com -
Private or gated model. Provide a token so the Hub authorizes the download:
export HF_TOKEN=hf_xxxopenmed doctorreportsWARN hf_token: present=Falsewhen no token is set. -
Wrong identifier. Confirm the id (
org/model) or registry alias exists — see the Model Registry andopenmed models list.
Symptom. The first analyze_text / extract_pii / deidentify call takes noticeably longer than later
calls.
Cause. First use downloads model artifacts, then loads weights and the
tokenizer into memory. Model files remain in the filesystem cache. In-memory
weights and pipelines are reused only when calls share a ModelLoader (or run
through the shared REST runtime); separate top-level convenience calls can load
them again.
Fix. Warm the cache and reuse loaders rather than paying the cost per call:
- Pre-download once so later runs hit the cache: call
ModelLoader.load_model()(as in the offline example below) or run a model-backed request on a machine with network before going offline. ConstructingModelLoader()by itself does not download a model. - Reuse one
ModelLoader/pipeline instead of constructing a new one per document — see ModelLoader & Pipelines. - In the REST service, pre-load models at startup with
OPENMED_SERVICE_PRELOAD_MODELSand keep them resident withOPENMED_SERVICE_KEEP_ALIVE— see REST Service.
Symptom. You want no network calls after startup, or an operation raises:
OfflineModeError: OPENMED_OFFLINE/local_only=True blocks outbound network access after model loading. Pre-download required model files into the configured cache, pass a local model path, or disable offline mode before remote fetches. Blocked action: socket connection.
Cause. Local-only mode is active (OPENMED_OFFLINE=1 or OpenMedConfig(local_only=True)). It passes
local_files_only=True to Hub loaders, sets HF_HUB_OFFLINE=1, TRANSFORMERS_OFFLINE=1, and
HF_DATASETS_OFFLINE=1, and blocks outbound sockets during inference. The error means an operation tried to
reach the network after the model was loaded — usually because the required files were not cached first.
Fix. Warm the cache before enabling offline mode, then turn it on:
# 1. Download once with network available (populates ~/.cache/openmed)
python -c "from openmed.core import ModelLoader; ModelLoader().load_model('disease_detection_superclinical')"
# 2. Then run strictly local
export OPENMED_OFFLINE=1from openmed.core import ModelLoader, OpenMedConfig
config = OpenMedConfig(local_only=True) # defaults to ~/.cache/openmed
loader = ModelLoader(config=config)You can also skip the Hub entirely by passing a local directory as model_name/model_id; OpenMed then
loads with local_files_only=True so a missing tokenizer, config, or weight file fails locally instead of
downloading. See Configuration & Validation and the
FAQ.
Symptom. Memory climbs when processing many documents, or a single very long document uses more memory than expected.
Cause. Each pipeline holds a model in memory, and long inputs are tokenized into large tensors. Creating a new pipeline per document multiplies resident memory.
Fix.
- Reuse one loader/pipeline across documents; do not build a fresh pipeline per call. See ModelLoader & Pipelines.
- Batch repeated work through the batch processor rather than looping one call at a time — see Batch Processing.
- Long inputs use sentence windows and tokenizer limits by default.
analyze_textenables sentence detection and groups sentences into bounded windows, while the tokenizer uses the model's maximum length (truncation=True). A single oversized sentence can still be truncated. Pass an explicitmax_lengthto bound per-request memory, or settruncation=Falseonly when you have verified the input fits. - In the REST service, bound the working set:
OPENMED_SERVICE_MAX_RESIDENT_MODELS(LRU eviction),OPENMED_SERVICE_MODEL_MEMORY_BUDGET_BYTES, andOPENMED_SERVICE_MAX_TEXT_LENGTH(defaults to 1,000,000 characters; requests above it are rejected). Use the model-lifecycle endpoints to unload models. See REST Service.
Symptom. A streaming de-identification run raises:
StreamingBufferError: carry-over buffer exceeded max_buffer before any prefix could be finalized; increase max_buffer for this stream
Cause. The carry-over buffer that keeps entity spans intact across chunk boundaries grew past max_buffer
before a safe prefix could be emitted — typically a very long unbroken run of text.
Fix. Increase max_buffer above the longest identifier or unsplittable text run the stream must retain.
Changing the source chunk size alone does not make an overlong unsafe tail safe to emit.
Symptom. You want to control which device inference runs on, or a GPU is not being used.
Cause. The PyTorch device default is "auto": OpenMed probes MPS, then CUDA, then falls back to CPU.
Explicit config or environment values override that choice; MLX is a separate backend and requires Apple
Silicon plus the matching dependencies.
Fix. Select the device through OpenMedConfig or environment variables:
from openmed.core import OpenMedConfig, ModelLoader
config = OpenMedConfig(device="cuda") # or "cuda:1", "mps", "cpu"
loader = ModelLoader(config=config)export OPENMED_DEVICE=cuda:1 # legacy alias
export OPENMED_TORCH_DEVICE=cuda:1 # PyTorch backend deviceSet only one of those variables when possible; OPENMED_TORCH_DEVICE takes precedence over the legacy
OPENMED_DEVICE. The auto-detection order is MPS → CUDA → CPU, and "gpu" is normalized to "cuda".
If you request device="cuda" on a host without CUDA, PyTorch raises its standard device error (for example
AssertionError: Torch not compiled with CUDA enabled or RuntimeError: No CUDA GPUs are available) — fall
back to device="cpu" or install a CUDA-enabled PyTorch build. See
Configuration & Validation.
Symptom. You are on an Apple-Silicon Mac and want acceleration, or an MLX-only artifact fails on a non-Apple host.
Cause. MLX runs only on Apple Silicon. On other hosts, OpenMed substitutes
matching PyTorch repositories for the supported privacy-filter MLX family.
Other MLX-only token-classification artifacts have no general automatic
fallback; select a compatible upstream PyTorch model explicitly. MLX
language-model features also have no non-MLX fallback and require mlx-lm:
ImportError: mlx-lm is required for OpenMed MLX language models. Install with: pip install openmed[mlx]
Fix. On Apple Silicon, install the MLX extra and verify the backend resolves:
pip install "openmed[mlx]"
python -c "from openmed.core.backends import get_backend; print(type(get_backend()).__name__)"For the PyTorch MPS path and its tuning defaults, see MLX Backend and
Torch MPS Performance. On non-Apple hosts, keep device="cpu" or device="cuda".
Symptom. A call to the public API raises one of:
ValueError: Input text cannot be None
ValueError: Input text cannot be empty
ValueError: Input text too long. Maximum length: <n>
Cause. OpenMed validates inputs before inference. Empty, None, or over-length text is rejected up front
so API clients get a clear error instead of a downstream crash.
Fix. Pass non-empty text; strip/guard user input before calling. If you need a length ceiling, set it explicitly with the validation helper:
from openmed.utils.validation import validate_input
# validate_input strips surrounding whitespace automatically.
text = validate_input(user_supplied_text, max_length=2000, allow_empty=False)Symptom. A PII call with an unrecognized lang raises:
ValueError: Unsupported language 'xx'. Supported: [...]
Cause. PII extraction and de-identification support 42 supported PII
language codes: am, ar, as, bn, cs, da, de, el, en, es, fa, fr, gu, he, hi, id, it, ja,
kn, ko, ml, mr, nl, no, or, pa, pl, pt, ro, ru, sv, sw, ta, te, th, tr, uk, ur, vi, xh, zh, and zu.
Russian currently uses a documented multilingual default-model placeholder.
Passing anything outside that set (or a mistyped code) raises this error.
The optional Indic NER adapter can serve Assamese, Bengali, Gujarati, Hindi,
Kannada, Malayalam, Marathi, Odia, Punjabi, Tamil, and Telugu when configured
with an explicit model or OPENMED_INDIC_NER_MODEL.
Fix. Use a built-in code with extract_pii(..., lang="<code>"), or
configure an explicit model for a registered user-supplied route. Clinical NER coverage depends
on the selected registry model — check each model's languages in the
Model Registry. See the FAQ.
Symptom. deidentify(..., method="…") with an unknown method raises:
ValueError: method must be one of ('mask', 'remove', 'replace', 'hash', 'shift_dates', 'format_preserve')
Cause. deidentify() accepts a fixed set of methods (default method="mask"). A typo or unsupported
value is rejected.
Fix. Pick a valid method for your reversibility needs (see the FAQ and PII Anonymization):
from openmed import deidentify
# Synthetic example only; do not paste real patient text into documentation or issues.
result = deidentify("Patient John Doe, DOB 01/15/1970", method="mask")
print(result.deidentified_text) # read output from .deidentified_text (not .text)!!! warning "Common de-identification gotchas"
- Read results from result.deidentified_text, not result.text.
- Redacted output is not reversible by itself. For an authorized reversible workflow, pass
keep_mapping=True and restore with reidentify(result.deidentified_text, result.mapping). The mapping
contains raw identifiers and must be protected as PHI. Date shifts can also be reversed by someone who
knows the offset.
- date_shift_days requires method="shift_dates" (otherwise
ValueError: date_shift_days requires method='shift_dates'), and patient_key requires
date_shift_secret (ValueError: patient_key requires date_shift_secret).
- Detection is an assistive control, not a substitute for a privacy review. Always inspect output before
release.
Symptom. Starting the API fails with ModuleNotFoundError: No module named 'fastapi' (or uvicorn).
Cause. The REST surface (fastapi, uvicorn, tracing/observability deps) lives in the service extra.
Fix. Install the extra and launch the ASGI app with uvicorn:
pip install "openmed[service]"
python -m openmed.service.logging --host 127.0.0.1 --port 8080Tune behavior with OPENMED_SERVICE_* variables, e.g. OPENMED_PROFILE=dev,
OPENMED_SERVICE_PRELOAD_MODELS, OPENMED_SERVICE_MAX_TEXT_LENGTH, and
OPENMED_SERVICE_TRUSTED_HOSTS (defaults to loopback only). See REST Service,
REST Authentication, and REST Tracing.
Keep the loopback bind for local troubleshooting. Before exposing the service on a network, configure
authentication, TLS at the ingress or reverse proxy, and an exact trusted-host allowlist.
Symptom. Launching the MCP server raises:
MissingExtraError: The MCP SDK is not installed. Install OpenMed with the MCP extra: pip install "openmed[mcp]".
Cause. The Model Context Protocol SDK lives in the mcp extra.
Fix. Install the extra and run the server module. It defaults to stdio transport; use
streamable-http to serve over HTTP:
pip install "openmed[mcp]"
python -m openmed.mcp.server # stdio (default)
python -m openmed.mcp.server --transport streamable-http --host 127.0.0.1 --port 8081The HTTP transport reads OPENMED_MCP_HOST (default 127.0.0.1), OPENMED_MCP_PORT (default 8081),
OPENMED_MCP_PATH (default /mcp), and OPENMED_MCP_TRANSPORT (default stdio).
Symptom. Starting the optional Typer interface with
python -m openmed.cli.typer_app prints:
[red]Typer/Rich not installed. Install with `pip install .[cli]` or `pip install typer rich`.[/red]
Cause. The optional rich terminal UI depends on rich and typer, which live in the cli extra. The
standard openmed command uses argparse and does not need this extra.
Fix.
pip install "openmed[cli]"
python -m openmed.cli.typer_app --helpUse openmed --help for the standard CLI (init, analyze, batch, deid,
pii, audit, risk, models, config, doctor, and more).
- Run
openmed doctorand include its output when reporting a problem. - Check the FAQ for conceptual questions (offline use, model selection, reversibility).
- Review Configuration & Validation for cache paths, device selection, profiles, and environment overrides.
- If you believe you found a bug, open an issue at
maziyarpanahi/openmed with the error text, the command
you ran, and your OpenMed version (
openmed doctorreports it). Use only synthetic text in reproductions, and remove patient content, reversible mappings, access tokens, credentials, and private model URLs from commands, tracebacks, logs, and screenshots before sharing them.