Mitigating NATS Errors and Optimizing Data Transfer in DBConvert Streams.

Managing data flow in distributed systems can be complex. This article explores common NATS errors in DBConvert Streams, their origins, and practical solutions, emphasizing the role of the dataBundleSize parameter in preventing these errors.

Mitigating NATS Errors and Optimizing Data Transfer in DBConvert Streams.

DBConvert Streams utilizes the NATS messaging system to stream data between source and target databases. It operates by bundling multiple rows from a table into a single message, which is then sent to the NATS system to be consumed on the target side.

The complexity arises from the variability of row sizes, which can differ significantly depending on the number of fields in a table and the data types of those fields. Predicting the optimal bundle (or batch) size that would prevent the 'maximum payload exceeded' and 'NATS: slow consumer, message dropped' errors is challenging.

Let's decode these errors, explore their origins, and unlock viable solutions.


This article will explore some common errors you might encounter when using the NATS messaging system with DBConvert Streams. We'll delve into their causes and provide practical solution to manage and resolve these errors.

Distributed systems are notorious for their complexity. One stands out among the many challenges they present: ensuring smooth, efficient data flow. It is especially critical when working with NATS, a popular messaging system in contemporary distributed environments.

Understanding the NATS Slow Consumer Error

A slow consumer in the NATS ecosystem refers to a consumer who can't keep up with the pace of incoming messages from the NATS server. It's like trying to drink from a firehose: the volume of data is simply overwhelming.

Slow consumers cause a domino effect in your system. As they lag in processing data, they create what's known as back pressure. This back pressure is not just limited to the consumer; it affects the entire system, leading to decreased performance and potential data loss.

Why does this happen? In distributed systems, generating data is much less labor-intensive than processing it. This means that data can be produced at a higher rate than it can be consumed, leading to a data pile-up and, ultimately, the slow consumer error.

Addressing Message Dropped and Payload Exceeded Errors in NATS

When a subscriber cannot keep up with the incoming message flow in NATS, it affects the subscriber and puts strain on the entire system. This strain often leads to dropped messages, potentially triggering the 'maximum payload exceeded' error.

By default, the NATS server and DBConvert Streams have a maximum message payload limit of 1MB. NATS raises the 'maximum payload exceeded' flag if a message exceeds this limit.

To visualize this, imagine trying to fit an oversized suitcase into the overhead compartment of an airplane. If the suitcase is too large, it simply won't fit, just like a message exceeding the payload limit.

These errors typically occur on the source side when publishing a message from the source to NATS, meaning the message is already too large before it even reaches NATS.

While increasing NATS payload size up to 8MB or even up to 64MB might seem straightforward, it can lead to higher memory use and potential performance issues. Therefore, it's recommended to consider all aspects and implications before adjusting the NATS max_payload setting.

Tackling NATS Errors in DBConvert Streams

Now that we've explored the genesis of these errors, let's dive into the solution. If you're working with DBConvert Streams, these issues can be mitigated by adjusting the dataBundleSize parameter in the stream configuration.

The default value for dataBundleSize is set at 100, which is well-suited for regular tables. However, this default value may prove excessive for tables with larger or "fat" records. To clarify, dataBundleSize signifies the cumulative number of rows read from a source and transferred to NATS in a single operation.

  "source": {
    "type": "mysql",
    "mode": "convert",
    "connection": "root:123456@tcp(",
    "dataBundleSize": 40,
    "filter": {
      "tables": [
        { "name": "fat-rows-table"}
  "target": {
    "type": "postgresql",
    "connection": "postgres://postgres:postgres@localhost:5432/postgres"
typical stream configuration with custom dataBundleSize parameter 

In addition to these considerations, it's essential to address other potential errors that may arise during data transfer. One common error users may encounter is as follows:

Error: Data size  exceeds max payload.

What to do if you are encountering an error like

[source] data size 2.0 MB exceeds max payload 1.0 MB

This error is likely occurring because records in the source table are too large. When transferring data between a source database and the target, data is combined from the source tables into bundles and then published to NATS. To resolve this issue, you can set the dataBundleSize parameter to a lower value.

If the problem persists even after adjusting the parameter value down to 1, modify the NATS configuration: You need to increase the max_payload parameter in the NATS configuration to 8MB.

debug: true
trace: false

# Each server can connect to clients on the internal port 4222 
# (mapped to external ports in our docker-compose)
port: 4222

# Persistent JetStream data store
jetstream = {
  # Each server persists messages within the docker container
  # at /data/nats-server (mounted as ./persistent-data/server-n… 
  # in our docker-compose)
  store_dir: "/data/nats-server/"
max_payload: 8MB
NATS sample config

version: '3.9'
    container_name: nats
    image: nats
    entrypoint: /nats-server
    command: "-c /etc/nats/nats.conf -m 8222"
      - 4222:4222
      - 8222:8222
       - ./nats/:/etc/nats
   # other services follows here 


In conclusion, understanding these nuances is key to effectively managing and resolving these errors within DBConvert Streams. By optimizing your message sizes and ensuring they fall within the allowable limits, you can prevent message drops and "payload exceeded" errors. This promotes smoother data flow within your NATS system and ensures efficient data transfer between your source and target databases.

The dataBundleSize parameter essentially controls the size of data packets. By fine-tuning this setting, you can achieve a balance between the rate of data production and consumption, effectively reducing back pressure and preventing data overflow.

Distributed systems are complex entities, and finding the perfect balance may take trial and error. But with a clear understanding of common errors and their solutions, you'll be well-equipped to keep your distributed systems running smoothly.

Give DBConvert Streams a try today and experience the difference it can make in your data management tasks!