Troubleshoot Data Streams

Symptom Likely causes Actions
REST returns 401 Missing or invalid credentials; proxy authentication mismatch. Verify the authentication mode, secret, clock where relevant, and proxy route. Do not embed credentials in the URL.
REST returns 403 Account lacks the required User, Operator, or Administrator role. Use the role table in Prerequisites for Data Streams Configuration and grant only the required permission.
WebSocket returns 404 or handshake failure Hardcoded channel path; proxy did not route or upgrade; wrong stream name. Retrieve the generated YAML and use its host and channel address. Validate WebSocket upgrade headers.
TLS verification fails Unknown CA, expired certificate, host mismatch, or missing client certificate. Install the correct CA chain, confirm DNS and certificate SAN, and configure mutual TLS when required.
Connection succeeds but no records arrive begin=now with no new commits; filter excludes data; wrong trail/path; Extract not writing. Generate a known transaction, inspect the source trail, temporarily simplify filters, and verify the stream source.
First object is not DML Schema and metadata records are expected before data. Classify every object; cache schema and metadata instead of treating them as errors.
JSON parser expects an object but receives an array WebSocket message is a batch. Parse the top-level array and iterate its records.
Client cannot reconnect with pos Token not percent-encoded, altered, belongs to another stream, or trail history was purged. Use the exact saved token, percent-encode it, verify scope, and follow the unavailable-position recovery procedure.
Duplicates appear atLeastOnce; crash between sink write and checkpoint; two consumers share checkpoint; non-idempotent retry. Use atomic checkpointing or idempotency and verify quality of service and consumer ownership.
Records are missing after recovery atMostOnce skipped an unavailable position; checkpoint saved before business commit; filters changed. Audit the recovery event, reconcile the data gap, and use exactlyOnce plus a correct checkpoint transaction for durable workloads.
Before or after image lacks columns Source logging or Extract captured a partial image; nulls omitted; row model selected. Inspect trail capture, omitNullColumnValues, model, and runtime schema. Do not infer absent fields as null.
DDL is missing DDL not captured, filter excludes DDL, or source configuration does not support the expected event. Validate source DDL capture and include DDL in operation filters.
Consumer fails after DDL Cached schema is stale or downstream cannot accept the change. Replace cached schema/metadata when new records arrive and execute the governed schema migration policy.
Large record is truncated or split maxLobSize, maxDDLTextSize, maxRecordSize, proxy limit, or client limit. Increase validated limits, select chunk handling when supported, and raise proxy/client message limits.
Numeric precision changes JSON number parsed as binary floating point. Use decimal-aware parsing or treatAllColumnsAsStrings.
Consumer memory grows Slow downstream processing, unbounded queue, oversized batches, or reconnect loop. Bound queues, decouple receive from processing, tune batch sizes, and scale or throttle downstream work.
CloudEvents consumer cannot find fields GoldenGate record is under data or runtime envelope values differ from a copied example. Unwrap data and use the runtime YAML and actual event attributes.

Information to collect for support