Astra Migration Operational Caveats
This page is the operational caveats and troubleshooting reference for migrating from DataStax Astra DB to open-source Apache Cassandra using the ZDM Proxy and the Cassandra Data Migrator (CDM) bulk-copy tool. In this guide Astra is the origin, reached through its Secure Connect Bundle, and an open-source Apache Cassandra cluster is the target. For the overall workflow, see the migration overview, the ZDM and CDM setup, and the data migration step.
Each item follows a Symptoms, Diagnostics, Resolution, Root Cause structure.
Before migration
Section titled “Before migration”Dedicated migration infrastructure is required
Section titled “Dedicated migration infrastructure is required”The ZDM Proxy and the bulk-copy tool run on their own instances; they must not be co-located on the target cluster, where they would compete for resources with the database itself. Plan for at least three proxy instances (for availability and to spread client load), a jumphost or monitoring instance, and a dedicated copy host for the bulk-copy tool. Sizing this infrastructure ahead of time avoids reworking the topology mid-migration.
The target schema, roles, and credentials must exist first
Section titled “The target schema, roles, and credentials must exist first”Symptoms: Writes to the target fail immediately after the proxy is deployed. Clients see authentication failures, or errors such as "keyspace does not exist" or "table does not exist".
Diagnostics: Confirm the target already holds every keyspace, table, role, permission and password that the application expects. Verify that all of the target nodes report UN (Up/Normal) with nodetool status.
Resolution: Recreate all keyspaces, tables, roles, permissions and credentials on the target before deploying the proxy. Treat schema and security objects as a prerequisite of the setup step, not something to add later.
Root cause: The bulk-copy tool migrates user table data only; it does not copy system tables, so credentials and schema are never carried across automatically. Dual-writes begin the instant the proxy is deployed, and a write that targets a missing schema object or role fails and can propagate back to the client.
Review collection, UDT, and TTL caveats
Section titled “Review collection, UDT, and TTL caveats”Symptoms: After the bulk copy, some rows that involve collections, user-defined types (UDTs), or per-cell TTLs differ between Astra and the target.
Diagnostics: Run the copy tool in validation mode and inspect its mismatch and missing-row reports to see which data shapes diverge.
Resolution: Understand how the copy tool handles collections, UDTs and TTLs before the run, set the job parameters to match the data model, and run the appropriate autocorrect pass to reconcile differences. See the validation step for the consistency check.
Root cause: The way collections, UDTs and per-cell TTLs are read and rewritten during a bulk copy can differ from the source's internal representation, so a naive copy may not be byte-for-byte identical without tuning.
During migration
Section titled “During migration”Dual-writes start immediately
Section titled “Dual-writes start immediately”The instant the proxy is deployed, every write goes to both Astra and the target. There is no deploy-now, enable-later window: dual-writing is active from the first request the proxy handles. This is precisely why the target schema, roles and credentials must exist first, because a write to an object that is missing on the target will fail.
Monitor the proxy layer alongside the databases
Section titled “Monitor the proxy layer alongside the databases”Symptoms: Astra and the target both appear healthy, yet clients still see intermittent errors or elevated latency.
Diagnostics: Inspect the ZDM Proxy metrics (origin reads, dual reads, target reads, and write outcomes) in addition to the metrics from each cluster.
Resolution: Keep proxy-layer monitoring running for the full duration of the migration, not just at cutover. The AxonOps ZDM Proxy fork exposes additional metrics that make this layer easier to observe.
Root cause: Problems that live in the proxy layer are invisible to monitoring that only sees each database in isolation; a view spanning the proxy itself is required.
Some copy errors are unavoidable
Section titled “Some copy errors are unavoidable”Symptoms: The copy logs retain a small set of errors even after multiple passes.
Diagnostics: Confirm that the residual errors are a known, understood and acceptable set, rather than a sign of a systemic problem with the job configuration.
Resolution: An acceptable residual error set is bounded, explained by known source-data conditions, and reconciled against the validation row counts rather than a sign of a systemic problem with job configuration. Minimise the time between the final autocorrect validation pass and switching reads to the target, and monitor the verification output closely throughout that window.
Root cause: Certain data shapes cannot be perfectly reconciled by a bulk copy. Because a small unreconciled set may persist, the safe approach is to keep the window between final validation and read cutover as short as possible.
Counter tables need explicit configuration
Section titled “Counter tables need explicit configuration”Symptoms: Counter values are missing on the target after the copy completes.
Diagnostics: Check whether the counter tables were included in the copy job at all.
Resolution: Enable the missing-counter autocorrect option, provided the application does not issue deletes against counter tables.
Root cause: By default the copy tool does not copy counter tables when values are missing, because counters cannot be safely re-applied in every case; the behaviour must be enabled deliberately.
Counters do not fit the dual-write flow
Counter values missing or wrong on the target is usually a symptom of a deeper issue: counter updates are not idempotent, so the dual-write and bulk-copy pattern can double-count or drop increments that occur during the migration. Counter tables must be migrated as a separate, dedicated step rather than through the standard flow. See Counter tables need special handling in the data migration phase for the recommended approach.
Finalising migration
Section titled “Finalising migration”System reads stay on Astra while the proxy is in place
Section titled “System reads stay on Astra while the proxy is in place”Symptoms: During cutover, reads against system and system_auth still appear to hit Astra, even after application reads have been switched to the target.
Diagnostics: Distinguish system-table reads from user-data reads in the proxy metrics to determine exactly which traffic is going where.
Resolution: This behaviour is expected. Confirm that all non-system reads are hitting the target, then point clients directly at the new cluster and remove the proxy; at that point system reads move to the target as well. See cutover and drivers.
Root cause: The proxy always routes system-table reads to the origin for as long as it remains in the query path, so system reads only move once the proxy is removed.
Run repair after the copy completes
Section titled “Run repair after the copy completes”Symptoms: Immediately after the copy, replica consistency on the target is lower than expected.
Diagnostics: Check the repair status and coverage across the target nodes.
Resolution: After a successful validation pass, run a rolling full repair over partitioner ranges (nodetool repair -pr --full) across all target nodes. See the validation step for the validation that should precede it.
Root cause: A bulk copy populates data without exercising Cassandra's normal replication and anti-entropy paths, so the replicas need repair to reach full consistency.
How AxonOps helps
Monitoring that spans both the proxy and the target cluster makes several of these caveats easier to catch early, because proxy-layer issues and target-side consistency gaps surface in one place rather than in isolated tools. See AxonOps for Cassandra.