OGG-02454 Trail Not Found in Checkpoint File When Migrating a Coordinated Replicat

When migrating a Coordinated Replicat for a client, I faced a very specific OGG-02454 error that I wanted to share. When using the migration utility on a Classic Architecture Coordinated Replicat, every attempt failed at the checkpoint conversion step with OGG-02454 Trail ... not found in checkpoint file. Because the migration utility rolls back the entire migration on any hard failure, one coordinated replicat anywhere in a multi-process migration seemed to prevent the migration to continue.

The failure was a trail path mismatch: with a coordinated replicat, the coordinator checkpoint file records the trail as an absolute path, but the migration utility uses convchk with the relative trail path the group was originally added with (EXTTRAIL ./dirdat/cc, for instance).

In the end, it was a patching issue, but the fix was not really the one I anticipated.

Lab setup

During these tests, I used the latest GoldenGate version (23.26.3.0.0) and the latest build of the migration utility (ogg-migration-package-23.26.2.0.3.jar, build 142).

The replicat under test is a coordinated replicat with MAXTHREADS 3 and two actively mapped threads on the Classic Architecture side:

OGG> ADD REPLICAT REPCC, COORDINATED MAXTHREADS 3, EXTTRAIL ./dirdat/cc, CHECKPOINTTABLE OGGADMIN.CHECKPOINT
REPLICAT (Coordinated) added.

Here is the parameter file, splitting two tables across two threads:

REPLICAT REPCC
USERIDALIAS tgt_pdb2
MAP PDB1.APP_PDB1.TCC,  TARGET APP_PDB2.TCC,  THREAD (1);
MAP PDB1.APP_PDB1.TCC2, TARGET APP_PDB2.TCC2, THREAD (2);

REPCC was running and applying end to end before anything was stopped. Only then was it stopped cleanly, alongside its extract, before the migration utility was run against the classicHome.

One word about coordinated replicat checkpoint files: a coordinated replicat does not keep its state in one checkpoint file. It keeps a coordinator file plus one file per thread, numbered 000 through MAXTHREADS. With MAXTHREADS 3, I had:

REPCC.cpr (coordinator)
REPCC000.cpr REPCC001.cpr REPCC002.cpr REPCC003.cpr (per-thread)

Migration failure

The migration utility processes extracts first, then replicats, in the order it discovered them. The extract EXTCC migrated cleanly, but when reaching REPCC:

Migration of Extract EXTCC Completed Successfully.
Migrating REPLICAT REPCC to http://localhost:7810.
Parameter File repcc.prm Saved Successfully.
ERROR: Conversion of checkpoint file for REPCC failed.
Migration of Replicat REPCC Failed!
Rolling Back All Changes.
All Changes were Rolled Back Successfully.
    Migration of Extract EXTCC ......: Successful
    Migration of Replicat REPCC .....: Failed
Migration Aborted.

The failing step was a convchk call, and the logs were rather clear: convchk runs the same trailpath conversion, with the same relative path, for both EXTCC and REPCC. However, only the coordinated replicat failed.

Issuing [.../convchk EXTCC ./dirdat/cc trailpath cc]
convchk exit code is 0 (successful execution)
Issuing [.../convchk REPCC ./dirdat/cc trailpath cc]
convchk exit code is 1 (execution failure)

2026-08-13  ERROR  OGG-02454  Trail ./dirdat/cc not found in checkpoint file
                              /u01/.../ogg_test_01/var/lib/checkpt/REPCC.cpr.

Of course, I tried creating the same replicat on the target deployment. Without any surprise, it worked. So the replicat itself is entirely valid on Microservices Architecture. The migration utility is the only thing that cannot create it, and only because of the trail path issue with convchk.

Origin of the error

The trail path information is located in the coordinator file. Running convchk showch on the checkpoint files shows exactly how each checkpoint file stores the path:

Name: REPCC     Coordinated Replicat Coordinator   Master: Yes
   File Name:  /u01/app/ogg/product/19.1.0.0.4_classic/dirdat/cc
Name: REPCC000  Coordinated Replicat Thread        Master: No
   File Name:  ./dirdat/cc
Name: REPCC001  Coordinated Replicat Thread        Master: No
   File Name:  /u01/app/ogg/product/19.1.0.0.4_classic/dirdat/cc
Name: REPCC002  Coordinated Replicat Thread        Master: No
   File Name:  /u01/app/ogg/product/19.1.0.0.4_classic/dirdat/cc
Name: REPCC003  Coordinated Replicat Thread        Master: No
   File Name:  ./dirdat/cc

The coordinator and the two threads (REPCC001 and REPCC002) store the trail as the absolute path /u01/.../dirdat/cc. In fact, once a thread opens the trail, GoldenGate rewrites its stored path to the resolved absolute form. The two threads that never started (REPCC000, REPCC003, allocated by MAXTHREADS 3 but never mapped) still carry the relative ./dirdat/cc it was added with.

My understanding is that the migration utility reads the trail as ./dirdat/cc (the relative form the group was added with) and calls convchk REPCC ./dirdat/cc TRAILPATH cc. convchk looks for the string ./dirdat/cc in REPCC.cpr, the coordinator file, which holds the absolute form, does not find it, and abends with OGG-02454.

When testing by giving convchk the absolute path, the same command with the same checkpoint files succeeds:

> convchk REPCC /u01/app/ogg/product/19.1.0.0.4_classic/dirdat/cc TRAILPATH cc

Checkpoint input trail file path /u01/.../dirdat/cc has been updated to a
new trail file path cc for the Replicat group REPCC.
Checkpoint conversion successful for group REPCC.

It is the same for the EXTCC extract. The checkpoint file stores the relative path ./dirdat/cc, which matches what the migration utility gives to convchk. This is why the extract migration worked.

Patching Classic Architecture before migrating

As explained in the blog about using the migration utility, you should ensure that your source GoldenGate setup is at least patched to 200714. I tried patching and migrating, but it did not solve the issue at first.

What I was missing was that patching the Classic Architecture could not affect the migration. In fact, the convchk utility being used is the one from the new OGG_HOME, in version 23.26.3.0.0. The reason why you should patch your source setup before migrating is because it will affect the new trail files.

Patching an already-affected Classic home in place does not retroactively fix an existing coordinated replicat. What is important here is that the replicat should be restarted under the patched Classic OGG_HOME, and that it must generate a new trail file for the migration to work.

Roll over the trail after patching

Of course, recreating the replicat under the new home would work, but you just have to force the extract to roll over on a new trail file. Once the coordinated replicat catches up, you can attempt the migration again.

SEND EXTRACT EXTCC, ROLLOVER

Once the coordinated replicat reads the new trail file, convchk showch on its checkpoint shows a relative trail path (./dirdat/cc) instead of the absolute path. It matches what the migration utility passes to convchk, and the migration is successful.

Migration of Extract EXTCC ......: Successful
Migration of Replicat REPCC .....: Successful

To summarize, if you want to migrate coordinated replicats from a very old Classic Architecture setup, you should:

• Patch the Classic Architecture (the latest patch is 39740001 / 19.32).
• SEND EXTRACT <name>, ROLLOVER on every extract feeding a coordinated replicat.
• Let the replicat process pass the rollover point. You can check with INFO REPLICAT <name> that its current read position is in the new trail file, not the old one.
• Stop everything cleanly and run the migration utility as usual.