GoldenGate Replicat Abends Due to Invisible Index

Root Cause and Production-Safe Fix

GoldenGate Replicat failed with OGG-01296 mapping error due to an invisible unique index on the target table. Learn why invisible indexes break replication and how to fix it safely.

Introduction

Oracle GoldenGate is widely used for real-time database replication, but certain Oracle database features can unexpectedly impact Replicat behavior.

In this article, we will walk through a real-world GoldenGate Replicat failure caused by an invisible unique index on the target database. Although the index existed and was valid, Replicat was unable to initialize table mapping and aborted during startup.

Component ValueSource

Database . SRCDB_TEST

Target Database TRGDB_TEST

Schema APP_TEST

Replicat Process . REP_TEST01

Table "test_payroll_txn"

Key Column TXN_ACTION_ID

DDL Replication Enabled (filtered)

Index DDL Explicitly excluded

Problem Statement

After starting Replicat, the process immediately aborted:

OGG-01296 Error mapping from SRCDB_TEST.APP_TEST.test_payroll_txn
to TRGDB_TEST.APP_TEST.test_payroll_txn


OGG-01668 PROCESS ABENDING


Additional symptoms:

– No transactions processed

– No DML errors reported

– Replicat exited immediately after startup

Source vs Target Schema Comparison

Source Database

The source table contained a proper primary key and several supporting indexes:

TEST_PAYROLL_TXN_PK
UNIQUE | VISIBLE | PARTITIONED

Target Database

Only one index existed on the target:

TEST_987654_PK_RPL
UNIQUE | INVISIBLE | PARTITIONED

Root Cause Analysis

Key Index Was INVISIBLE

Although the index was:

• UNIQUE
• Defined on the correct key column
• Valid and usable for queries

GoldenGate relies on visible key structures to:

• Identify rows for UPDATE and DELETE
• Build internal metadata during Replicat startup
• Establish table-level mapping

Invisible indexes may be ignored during this phase, causing Replicat mapping failure.

The Fix (No Drop, No Rebuild)

Instead of dropping and recreating the index, the issue was resolved safely using:

ALTER INDEX APP_TEST.TEST_987654_PK_RPL VISIBLE;

Why This Works

• No index rebuild required
• No data movement
• No performance impact
• Immediate effect
• Replicat can now detect the key structure

This is the preferred production-safe fix.

Result After Fix

• Replicat started successfully
• Table mapping completed without errors
• Data replication resumed normally
• No further abends observed

Key Takeaways

Invisible Indexes Are Unsafe for GoldenGate Keying

Even if an index is unique and correct, GoldenGate may not recognize invisible indexes for replication mapping.

Excluding Index DDL Requires Careful Target Preparation

If index DDL is excluded:

• Required PK/UK indexes must exist on target
• They must be VISIBLE
• Schema alignment must be intentional

Best Practices for GoldenGate Replication

• Avoid invisible indexes on replicated tables
• Ensure PK/UK constraints or visible unique indexes exist
• Validate index visibility before starting Replicat
• Document required target-side objects when excluding DDL
• Use invisible indexes only for optimizer testing, not replication correctness

High-Level Flow (Replication Model)

Think of Replicat startup like a metadata validation phase before any data moves.

Replicat START
|
v
Read table metadata (columns, constraints, indexes)
|
v
Determine KEY for UPDATE / DELETE
|
v
Can a stable key be resolved?
| |
YES NO
| |
v v
Apply DML OGG-01296
successfully Mapping failure

Key Resolution Priority Order (Very Important)

When Replicat decides how to uniquely identify rows, it checks objects in this order:

1️⃣ Primary Key constraint (P)
2️⃣ Unique Key constraint (U)
3️⃣ Visible UNIQUE index
4️⃣ KeyCols / explicit key mapping (if configured)
5️⃣ ❌ Failure (no usable key)

What Happened in our Case

Source Side

Replicat has a clear key definition on source

Table: "test_payroll_txn"

Primary Key:
TEST_PAYROLL_TXN_PK
UNIQUE | VISIBLE | PARTITIONED

Target Side (Before Fix)

Table: "test_payroll_txn"

Indexes:
TEST_987654_PK_RPL
UNIQUE | INVISIBLE | PARTITIONED


Problems:

• No PK constraint
• Only key index was INVISIBLE
• Replicat could not “see” a valid key

Why INVISIBLE Index Breaks Replicat

Invisible indexes are designed so that:

• Optimizer ignores them
• SQL execution does not consider them
• They exist or been changed only for testing

GoldenGate Replicat behaves similarly — during metadata resolution:

VISIBLE index? ❌ No
PK constraint? ❌ No
UK constraint? ❌ No
---------------------
Result: ❌ No usable key


Replicat fails with:

OGG-01296 Error mapping table
OGG-01668 PROCESS ABENDING


Making the Index Visible Fixes the issue

Instead of dropping/recreating, you used the correct fix:

ALTER INDEX APP_TEST.TEST_987654_PK_RPL VISIBLE;


What Changed Internally

Before:
UNIQUE + INVISIBLE → Ignored by Replicat

After:
UNIQUE + VISIBLE → Accepted as replication key


Now Replicat sees:

✔ Visible UNIQUE index available
✔ Key resolved
✔ Mapping succeeds
✔ Replication starts

Comparison (Before vs After)

Before (Failure)

Replicat
|
v
Target Table Metadata
|
├─ PK constraint ❌
├─ UK constraint ❌
└─ UNIQUE index (INVISIBLE) ❌
|
v
OGG-01296 ABEND

After (Success)

Replicat
|
v
Target Table Metadata
|
├─ PK constraint ❌
├─ UK constraint ❌
└─ UNIQUE index (VISIBLE) ✅
|
v
Key resolved → Apply DML

Conclusion

GoldenGate Replicat failures are not always caused by missing keys or data conflicts. In this case, a single invisible index caused Replicat to abort before processing any data.

Understanding how GoldenGate interprets database metadata — especially index visibility — is essential when operating production replication systems.