---
title: Troubleshooting Biotite
description: Fix missing DSSP or OpenMM, FASTA and GenBank parse errors, out-of-memory batches, and RMSD spikes from unmatched chain IDs — and when to retry instead.
---

This page helps you diagnose missing dependencies (DSSP/OpenMM), FASTA/GenBank parsing errors, out-of-memory failures on large batches, and unexpected RMSD spikes during structure alignment.

> **Where this code runs**

> You cannot open a shell on the platform yourself. The scripts on this page are plain Biotite Python and shell: ask Ivy in chat to run them in the chat's [code workspace](/docs/sandbox), which ships Biotite, or run them on your own machine.

## Common issues and fixes

**Missing DSSP/OpenMM** Install `biotite[full]` and confirm system packages are
present. In a local environment, add system deps like `libxml2-dev` if required by
your base image.

**FASTA/GenBank parsing errors** Ensure files are UTF-8 and contain header
lines. Run a preflight check:

```bash
python - <<'PY'
from biotite.sequence.io import load_sequence
import sys

for path in sys.argv[1:]:
    try:
        load_sequence(path, format=None)
        print(f"OK: {path}")
    except Exception as exc:  # noqa: BLE001
        print(f"FAIL: {path} -> {exc}")
PY inputs/sequences/*
```

**Out-of-memory on large batches** Process files one-by-one, avoid loading
entire archives into memory, and write partial outputs frequently to `outputs/`.

**Unexpected RMSD spikes** Strip waters/ligands before alignment and ensure
chain IDs match between reference and mobile structures.

## Logging tips

- Log input counts, skipped files, and final output paths.
- Capture Biotite version and dependency versions at startup for
  reproducibility.
- Add a lightweight summary JSON (counts, errors) alongside outputs.

## When to retry vs. fail fast

- Retry: network fetch errors or transient PyPI outages during install.
- Fail fast: missing mandatory inputs, empty sequences, or unsupported residue
  codes.

## Read next