Troubleshooting

Troubleshooting

UV not found

command not found: uv

Fix:

curl -LsSf https://astral.sh/uv/install.sh | sh
# Then add to PATH
export PATH="$HOME/.cargo/bin:$PATH"
# Or add to your shell profile:
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

---

Module not found

ModuleNotFoundError: No module named 'synthea'

Fix: Install the package in editable mode:

uv pip install -e .

---

Slow generation

Cause: Default single-threaded mode.

Fix:

uv run synthea -p 1000 --threads 8

Or add to config:

generate.thread_pool_size = 8

---

Out of memory for large populations

Fix: Generate in batches:

# 10 000 patients in batches of 1 000
for seed in $(seq 0 1000 9000); do
  uv run synthea -p 1000 -s $seed --threads 4 -o ./output
done

Or set exporter.append_mode = true and exporter.csv.export = true to stream rows incrementally.

---

No patients generated / stats show 0

Cause: Demographic filter too narrow — age range or gender filter has no matching patients in the selected location.

Fix:

1. Widen the age range: -a 0-99
2. Remove the gender filter
3. Try a different state / city

---

FHIR validation errors when posting to a server

Symptom: Server rejects bundles with 422 Unprocessable Entity.

Common causes and fixes:

Error	Fix
Missing required field: status on Condition	Upgrade to latest Synthea; default status was added
Unknown resource type	Ensure server supports FHIR R4 (not DSTU2 / STU3)
Narrative required	Set exporter.fhir.transaction_bundle = false and use collection type
Duplicate patient IDs	Run with exporter.use_uuid_filenames = true

---

Reproducibility — same seed gives different output

Cause: Using more than 1 thread. Thread scheduling is non-deterministic.

Fix:

uv run synthea -p 100 -s 12345 --threads 1

---

Module validation fails

KeyError: 'states'

Fix: Every module JSON must have a top-level states object and exactly one "type": "Initial" state and at least one "type": "Terminal" state.

Run the validator:

uv run python -m synthea.validate_module resources/modules/my_module.json

---

CSV files are empty after generation

Cause: CSV export is disabled by default.

Fix:

exporter.csv.export = true

Or add -c with a properties file that enables it.

---

Getting more help

• GitHub Issues — bug reports and feature requests
• GitHub Discussions — questions and community help
• Run with --log-level debug for verbose output that usually pinpoints the problem