Troubleshooting
The list below covers the questions that come up most often when
scoping and running a DBReplay engagement. Most of the early ones are
about the trial capture, since that's the first thing every engagement
does.
Trial capture
| Symptom | Likely cause | What to check |
|---|
| Capture completed but the file won't decode |
An older capture-tool default truncates each packet to a
small snap length. |
Confirm the capture was taken with a full snap length; a
rate that looks perfect and a file that won't decode is the
signature of this specific mistake. |
| Drop counters missing from the capture report |
The counter is only printed once, on exit, and easy to lose
if output wasn't redirected. |
Re-run with output captured to a file; this number is the one
the whole exercise exists to produce. |
| The capture set looks complete but the start is missing |
A size-based rotation without a file-count limit silently
wraps and overwrites the oldest file. |
Confirm the capture was sized to fit the whole window without
wrapping, not rotated indefinitely. |
| Byte rate looks fine but drops are still reported |
The counter used only reflects what the kernel received; ring
or NIC-level drops can happen earlier. |
Collect NIC counters before and after the capture window as
well as the capture tool's own counters. |
Encrypted sources
| Symptom | Likely cause | What to check |
|---|
| A wire capture of an encrypted source is unreadable |
Expected under TLS 1.3 — there is no server-private-key
route to decrypt after the fact. |
See TLS for the platform-level
clear-text trace and client-side alternatives, and whether either
applies to your source. |
| Statements captured but coverage looks unexpectedly low |
The DDF clients may sit on another host over an internal
network path that never reaches the tap point at all. |
Confirm where the clients actually live, not just where the
database does — see
Capture Topology. |
Coverage and translation
| Symptom | Likely cause | What to check |
|---|
| A statement is flagged untranslatable that looks routine |
The dialect changer has a mapping gap rather than the
statement being genuinely unsupportable. |
Confirmed real cases get added to the rule set and the
regression corpus; report it rather than working around it. |
| A static-SQL package can't be resolved to text |
A rebind between capture and catalog extraction can shift
section-to-text mappings while every name stays the same. |
Resolution matches on the consistency token, not just
collection/package/section — confirm the catalog extract's
timing relative to the capture. |
| The run refuses to start |
Unhandled SQL is a hard gate by design — a statement
with neither a mapping nor an explicit disposition stops the
run. |
Check the coverage report for the specific statement; it
needs either a rule or an explicit, justified disposition before
the run proceeds. |
Frequently asked questions
| Question | Answer |
|---|
| Does DBReplay connect to our live source system? |
No. Everything runs from a capture artefact and a catalog
extract your team produces. There is no live credential. |
| Does it modify the source in any way? |
No. Capture is passive and read-only; it cannot affect
production traffic. |
| Does the replay run against our production target? |
No. Replay runs against a disposable target environment
stood up for the engagement, restored between runs. |
| What if we can't get an unencrypted capture? |
Several routes exist depending on the source platform and
client location — see TLS.
Ask early; it's a scoping-call question, not a blocker discovered
mid-engagement. |
| How long does a trial capture take to arrange? |
Typically the same week — it's a plain packet capture
with no DBReplay software involved, and needs no unusual security
approval. |
| How is DBReplay licensed? |
As a product with consulting attached, licensed per migration
project. Contact Oninit for current terms. |
When to call Oninit
If a question isn't covered above, or your environment has anything
unusual about it — data-sharing groups, an internal-only network
path, a client platform other than Linux or z/OS — raise it during
scoping rather than at capture time. Call
+1 913 732 8892 (US) or
+44 20 8133 7529 (UK), or email
support.info@oninit.com.
