Back up Schema Registry with the topics that depend on it
Avro, JSON Schema, and Protobuf messages embed a schema ID that points at an external registry. Restore the data without the schemas and every consumer fails with 'Schema ID not found'.
Kafka Schema Registry backup in the same config
Kafka Schema Registry backup is one section added to the config you already run. The Enterprise edition captures every subject, every schema version, references, and both global and per-subject compatibility settings — in the same job as the topic data, stored in the same backend.
That coupling matters. A topic backup and a schema backup taken at different times can disagree, and a registry rebuilt from the wrong snapshot leaves consumers unable to deserialize restored records.
- backup.yaml
- Run it
- restore.yaml
mode: backup
backup_id: "daily-with-schemas"
source:
bootstrap_servers:
- broker-1.kafka.svc:9092
topics:
include:
- orders
- payments
storage:
backend: s3
bucket: my-kafka-backups
region: us-west-2
enterprise:
schema_registry:
url: "https://schema-registry:8081"
auth:
type: basic
username: ${SR_USERNAME}
password: ${SR_PASSWORD}
backup:
subjects:
- "orders-*"
- "payments-*"
exclude:
- "*-test"
include_versions: all
kafka-backup backup --config backup.yaml
# Schema-only snapshot (no Kafka data) — e.g. for a compliance archive
kafka-backup backup --config backup.yaml --schema-only
mode: restore
backup_id: "daily-with-schemas"
target:
bootstrap_servers:
- dr-broker-1.kafka.svc:9092
storage:
backend: s3
bucket: my-kafka-backups
region: us-west-2
enterprise:
schema_registry:
url: "https://dr-schema-registry:8081"
restore:
strategy: preserve
# Empty target registry: keep the original schema IDs
force_ids: true
# Rehearse the restore without registering anything
dry_run: false
Pick the restore strategy for the job
Schema restore runs automatically before data restore, and subjects are registered in dependency order — referenced schemas first. Three strategies cover the common scenarios:
| Strategy | Behavior on the target registry | Use case |
|---|---|---|
preserve (default) | Keep existing schemas; add what is missing | Merge or partial recovery |
overwrite | Replace existing schemas from the backup | Full DR to a clean target |
skip | Only register subjects that do not exist yet | Add new schemas only |
Two ID controls handle the hard cases. force_ids: true keeps original schema IDs
on an empty target via IMPORT mode. rewrite_ids: true rewrites the IDs embedded in
the Kafka message bytes when the target registry assigns different ones — the
cross-environment migration case. subject_mapping renames subjects on the way in,
so a production backup can populate a staging registry.
Schema Registry backup requires an Enterprise license with the schema_registry
feature enabled; topic backup, offsets, and point-in-time restore are open source.
For schema ID pitfalls, dependency ordering, and post-restore verification, read the
Schema Registry safe-restore runbook on the blog.
Frequently asked questions
Why do restored Kafka messages fail with "Schema ID not found"?
Messages serialized with Avro, JSON Schema, or Protobuf embed a 4-byte schema ID that references an external Schema Registry. If the data is restored but the registry was not, or was rebuilt with different IDs, consumers cannot resolve the ID and deserialization fails.
What does a Schema Registry backup include?
All subjects matching your filter patterns, every schema version with its type and references, global and per-subject compatibility levels, and registry modes. Cross-schema dependencies are recorded so restore can register schemas in the correct order.
Can I back up schemas without backing up topic data?
Yes. Run kafka-backup backup with the --schema-only flag to capture just the registry — useful for periodic compliance archives or before risky registry changes.
How do schema IDs survive a restore to a different registry?
Two options: force_ids uses IMPORT mode to keep the original IDs on an empty target registry, and rewrite_ids rewrites the IDs inside the restored Kafka message bytes when the target assigns new ones. Pick force_ids for clean DR targets and rewrite_ids for migrations.
Is Schema Registry backup part of the open source tool?
No. Schema Registry backup and restore is an Enterprise feature, alongside encryption, RBAC, and audit logging. Topic backup, consumer offset preservation, and point-in-time recovery are open source under MIT.
Ready to protect your Kafka data?
Take your first backup in minutes with the open source CLI, or talk to us about Enterprise features like encryption, RBAC, and audit logging.