Change Broker troubleshooting

Use this page to diagnose and resolve live issues when retrieving updates from Change Broker. Each issue section includes symptoms, likely cause, and resolution steps.

Note: Because response time scales with payload size and client-side processing throughput, some delay is expected for larger Get updates payloads. In this topic, sustained lag means observed end-to-end update delay that stays consistently above your normal processing baseline across multiple polling cycles, rather than returning to expected levels after short-term spikes. If sustained lag persists for five minutes or more after applying the guidance in this topic, contact AVEVA customer support.

Change Broker appears unavailable for the target account or service instance

This issue usually appears during onboarding when teams are unsure whether Change Broker is available for a specific account and service instance. It is typically caused by account or service instance setup gaps, or incorrect request targeting, and it is resolved by verifying setup before troubleshooting runtime behavior.

Symptoms

• Teams cannot confirm whether Change Broker is available for the target account and service instance.

• Create signup or signup retrieval calls are attempted against the wrong account or service instance.

• Troubleshooting starts with runtime assumptions before setup is validated.

Likely cause

• Change Broker is not available for the targeted account and service instance.

• Account and service instance identifiers in requests do not match the intended environment.

Resolution

• Verify Change Broker availability for the target account and service instance.

• Validate account and service instance values used in Create signup and signup retrieval requests.

• Submit a Create signup request to confirm availability for the targeted account and service instance.

• If Create signup succeeds, treat availability as confirmed. If you are continuing into update-query troubleshooting, poll Get signup by ID until the signup is Active and bookmarkInfo.bookmarkAvailable is true.

Get updates response payloads are much larger than expected

This issue refers to the response body returned by the Get updates endpoint for a signup, including the transactions and grouped data point units in that page. It usually appears as large Get updates responses and growing retrieval latency, and it is resolved by increasing query cadence and narrowing signup scope.

Symptoms

• Get updates responses are consistently large.

• Retrieval latency increases over time.

• Your client application spends most of its time processing backlogged updates.

Likely cause

• Polling cadence is lower than write volume.

• The signup includes streams that the client application does not need for its immediate objective.

Resolution

• Increase Get updates frequency so egress keeps pace with ingress.

• Limit each signup to the streams needed for that workflow.

• If your workflow only needs current state, reduce monitored scope and poll more frequently rather than processing large historical backlogs.

Ingress and egress rates are out of balance

This issue usually appears when new data arrives faster than your client application can retrieve and process it. It is typically caused by a cadence mismatch, and it is resolved by shortening polling intervals and ensuring consumer throughput keeps pace.

Symptoms

• New data is written quickly, but your consumer appears delayed.

• Update pages arrive near maximum size for extended periods.

Likely cause

• Ingress rate exceeds effective egress rate because query cadence is too slow.

Resolution

• Measure ingress rate and retrieval throughput per signup.

• Shorten polling intervals until observed lag stabilizes or decreases.

• Scale consumers so update processing does not become the bottleneck after retrieval.

Signups expire or become idle unexpectedly

This issue usually appears after long gaps between update requests, leading to bookmark or signup lifecycle problems. It is typically caused by infrequent interaction, and it is resolved by enforcing a minimum hourly query cadence and persisting the latest bookmark on every successful read.

Symptoms

• Update requests fail after long polling gaps.

• A previously valid signup later returns as expired, or returns 404 Not Found after inactivity.

Likely cause

• The signup is not queried often enough to keep bookmark and signup state active.

• Expired signups are automatically cleaned up after expiration (typically within the next hour), so later retrieval attempts can return 404 Not Found instead of an expired response.

Resolution

• Query each signup at least once per hour to avoid bookmark expiration. A higher polling frequency provides additional tolerance for temporary disruptions that could result in missed requests.

• Use a more frequent cadence for high-throughput signups.

• After each successful response, process the returned change data, then persist the latest bookmark and use it in the next request.

• If signup retrieval returns expired or 404 Not Found after inactivity, create a new signup and obtain a new bookmark before resuming update retrieval.

Very high stream counts make it difficult to stay current

This issue usually appears as persistent lag when retrieving pages from the Get updates endpoint for signups that monitor very large stream sets. It is typically caused by signup design and consumer capacity not matching workload volume, and it is resolved by rebalancing stream membership across signups and iteratively tuning signup composition.

Symptoms

• A signup with many streams shows sustained consumer lag, where Get updates processing does not catch up to newly ingested changes.

• Get updates polling and processing cycles overlap continuously.

Likely cause

• The signup design and consumer throughput do not match the monitored stream volume.

Resolution

• Keep signups focused on coherent workloads rather than one broad catch-all workload.

• Rebalance stream membership across signups when one signup becomes a sustained hotspot.

• Use iterative signup adjustments and verify lag improvement after each change.

Bookmark handling does not converge to current data

This issue usually appears when clients never catch up and responses remain near the 100,000 transaction page target. It is typically caused by treating bookmarks as optional checkpoints or polling too slowly, and it is resolved by strict cursor progression and immediate repolling while pages stay near that threshold.

Symptoms

• The client application never appears caught up.

• Responses remain at or near 100,000 transactions.

• Teams treat bookmarks as occasional checkpoints instead of strict progression cursors.

Likely cause

• Polling is too infrequent for current ingest rates.

• The client application does not continuously advance the latest bookmark.

Resolution

• Treat bookmarks as cursors, not as optional markers.

• After every successful Get updates response, process the returned change data first, then persist and use the returned bookmark.

• If processing fails before bookmark persistence, retry with the prior bookmark.

• When response size is at or near 100,000 transactions, immediately request the next page with the returned bookmark and continue until response size drops below that level.

• If this pattern persists for long periods, increase polling frequency and reduce signup scope.