Lesson 4: Troubleshooting ZDM – Common Errors & Fixes

Ashish Agnihotri

Data Analyst at Exaguru 

Introduction

Even though Oracle Zero Downtime Migration (ZDM) automates end-to-end migrations, DBAs often encounter environment-specific errors. These issues usually arise during pre-checks, staging, or cutover phases.
This lesson outlines the most common ZDM errors, their root causes, and fixes, following Oracle’s best practices.

🔹 ZDM Troubleshooting Architecture

  ZDM logging and diagnostics are structured across three layers:

1. ZDM Service Host Logs

      - Located Under:

                            $ZDM_HOME/logs/

      - Key Files:

                            zdm.log → High-Level Job Log

                            zdmlogger.log → Component Logging Framework

                            job_<ID>.log → Task-level log per migration job

2. Source Database Logs

       -RMAN logs, listener logs, alert logs (alert_<SID>.log).

3. Target Database Logs

       -DBUA upgrade logs (for cross-version migrations).

      - Standby creation logs (if Data Guard mode).

🔹 Common Errors & Fixes

1️⃣ Connectivity & Authentication Errors

Error Message:
 ZDM-10030: Unable to establish SSH connectivity with source/target node 
Cause:
  • SSH key not configured correctly.
  • Wrong hostnames or firewall restrictions.
Fix:
 # Test SSH manually ssh -i /path/to/key opc@target-node 
  • Ensure passwordless SSH between ZDM host ↔ source ↔ target.
  • Open required ports (22, 1521, Data Guard/GoldenGate ports).

2️⃣ Pre-check Failures

Error Message:
 ZDM-10142: Database version not supported for migration 
Cause:
  • Source database not on terminal release (e.g., 11.2.0.4 required for 11g).
Fix:
  • Patch/upgrade source to the minimum supported version.
  • Example: 11.2.0.4 PSU applied before attempting migration.

3️⃣ RMAN Backup Errors

Error Message:
 ORA-19504: failed to create file ORA-27040: file create error 
Cause:
  • Insufficient disk space for RMAN backup.
  • Wrong staging location in ZDM config file.
Fix:
  • Increase disk quota on ZDM host staging area.
  • Validate backupLocation parameter in zdm_service.cfg.

4️⃣ Data Guard Sync Issues

Error Message:
 ORA-16810: multiple errors or warnings detected for the database 
Cause:
  • Data Guard broker misconfiguration.
  • Network latency is impacting redo transport.
Fix:
 DGMGRL> show configuration; DGMGRL> edit database <dbname> set property LogXptMode='SYNC'; 
  • Validate redo apply lag.
  • Ensure ports (default 1521) are open and the MTU is consistent.

5️⃣ GoldenGate Replication Errors

Error Message:
 OGG-00519: Fatal error in Extract 
Cause:
  • Unsupported data type in replication.
  • Extract not granted required privileges.
Fix:
 GRANT DBA TO <ogg_user>; 
  • Add supplemental logging:
 ALTER DATABASE ADD SUPPLEMENTAL LOG DATA; 
  • Restart GoldenGate extract/replicat.

6️⃣ Cutover Failures

Error Message:
 ZDM-10502: Cutover failed due to application connections on source DB 
Cause:
  • Applications still connected during cutover.
Fix:
 ALTER SYSTEM QUIESCE RESTRICTED; 
  • Stop application services.
  • Retry cutover with:
 zdmcli resume job -id <JOB_ID> 

🔹 Best Practices for Troubleshooting

✅ Always run -precheck before migration to catch environment mismatches.
✅ Monitor logs in real-time:
 tail -f $ZDM_HOME/logs/job_<ID>.log 
✅ Use zdmcli query job to check job progress.
✅ Automate health checks with Ansible playbooks before ZDM runs.
✅ Document fixes in a runbook for repeatable migrations.

🔹 Example: Resume Failed Job

# Query the job status 
zdmcli query job -id 12345  
# Resume from failure 
point zdmcli resume job -id 12345 

🔹 Closing Thoughts

Troubleshooting ZDM requires understanding its multi-layered architecture: ZDM logs, source DB, target DB, and transport mechanisms (RMAN/DG/OGG). By mastering common error codes and their fixes, DBAs can ensure smooth migrations with minimal downtime and reduced risk.
This makes ZDM not only an automation tool but also a resilient migration framework when combined with strong troubleshooting practices.
 Next Step: Lesson 5: Comparing ZDM vs GoldenGate vs RMAN

Copyright@Exaguru

Contact Us: +91-6394049607