Configure Consensus Node Streaming
Overview
Scope: On Hedera mainnet and testnet,
application.propertiesis overwritten on each release by the Network Management Tool (NMT), andblock-nodes.jsonis generated and installed by NMT at deployment time. Manual edits to either file on managed nodes will be overwritten. This guide applies to private or permissioned networks where operators manage configuration directly.Private networks should also be aware that certain CN releases will introduce new default values — for example, the default streaming behaviour may change from writing records to local disk to streaming blocks to Block Nodes automatically. When a private network upgrades to such a release, a
block-nodes.jsonfile still needs to be installed to identify which Block Node(s) to stream to.
A Consensus Node (CN) produces a stream of block data and by default writes it only to local disk. To route that stream to a Block Node instead, two CN settings must point to streaming-enabled values and a block-nodes.json configuration file must exist on disk. Without this setup, a deployed Block Node receives nothing — the CN silently ignores it. This is the single most common silent failure in new Block Node deployments.
This guide shows how to:
Verify the two stream configuration settings that gate block streaming.
Create the
block-nodes.jsonfile that identifies which Block Node(s) to stream to.Confirm the streaming connection is active using CN logs and Block Node metrics.
Optionally tune advanced connection behaviour.
Prerequisites
Before you begin, ensure you have:
A deployed and healthy Block Node:
A running Consensus Node with permission to edit its
application.propertiesand thedata/configdirectory. See hiero-consensus-node releases for available versions.Network access from the CN host to the Block Node host on the Block Node's gRPC port. Port
40840is the historical default, but starting with Block Node 0.36 each service uses a separate port — consult your Helm values or release notes for the current publish-service port. Confirm reachability withnc -vz <BN_HOST> <PORT>before proceeding.
Step 1 — Verify stream configuration on the Consensus Node
Two CN settings control whether blocks are streamed at all. Both must be set to streaming-enabled values or the block-nodes.json file is completely ignored.
blockStream.writerMode
Controls where the CN writes blocks. Set in application.properties as blockStream.writerMode=<value>.
FILE
Write blocks to local disk only. block-nodes.json is completely ignored.
No
FILE_AND_GRPC
Write blocks to local disk and stream to Block Nodes via gRPC.
Yes
GRPC
Stream to Block Nodes via gRPC only. No local block files are written.
Yes
The current default is FILE_AND_GRPC. If your CN was configured with FILE (the value used before WRB streaming was enabled), change it to FILE_AND_GRPC or GRPC.
Note: The defaults for both
writerModeandstreamModematch the Hedera mainnet configuration and are hard-coded inBlockStreamConfig.java. Verify your CN's effective values rather than assuming the default applies.
blockStream.streamMode
Controls which stream type the CN produces. Set in application.properties as blockStream.streamMode=<value>.
RECORDS
Produce record streams only. Block streaming is disabled entirely.
BLOCKS
Produce block streams only.
BOTH
Produce both record streams and block streams.
The current default is BOTH. If this is set to RECORDS, block streaming is disabled regardless of writerMode. Ensure it is BOTH or BLOCKS.
Step 2 — Create block-nodes.json
The CN reads target Block Node addresses from a JSON file on startup and watches it continuously for changes.
File location
The file must be named exactly block-nodes.json and placed in the directory configured by:
The path is relative to the CN working directory. On mainnet and testnet this directory is managed by NMT and may change between releases; confirm the active path in the CN process environment or release notes before proceeding.
File schema
The file is a JSON object with a single nodes array. Each entry has the following fields:
address
string
Yes
Hostname or IP address of the Block Node. Must be resolvable by the CN's OS DNS stack.
streamingPort
integer
Yes
TCP port the Block Node listens on for incoming block streams. Default Block Node port: 40840.
servicePort
integer
No
TCP port for Block Node service APIs (e.g., serverStatus). Defaults to streamingPort if omitted.
priority
integer
Yes
Connection priority. Lower value = higher priority. 0 is the highest priority. Nodes with the same priority are selected randomly among available candidates.
messageSizeSoftLimitBytes
integer
No
Soft limit on per-request payload size in bytes. Requests are packed up to this size; an oversized single item may exceed it. Defaults to 2,097,152 (2 MB) if omitted.
messageSizeHardLimitBytes
integer
No
Hard limit on per-item payload size in bytes. Items larger than this value are rejected. Defaults to 131,072,000 (125 MB) if omitted.
Note: Both size limits must not exceed what the Block Node is configured to accept. Setting either limit higher than the Block Node's own
server.maxMessageSizeBytes(or equivalent) will cause streaming errors on oversized items.
Example: single Block Node
Example: two Block Nodes with failover
The CN connects to the highest-priority node available. If that node becomes unreachable, it falls back to the next priority group.
Live reload
The CN watches block-nodes.json for create, modify, and delete events. Changes take effect immediately — no CN restart is required. If the file is deleted or fails to parse, the CN logs a warning and stops establishing new Block Node connections until a valid file is present again.
Step 3 — Confirm streaming is active
On the Consensus Node
After creating block-nodes.json, watch the CN application log for these messages in order:
Starting block node connection manager...
CN has seen the config file and is initialising.
Block node configuration loaded (version: N)
block-nodes.json parsed successfully. N is a monotonically increasing counter that starts at 1 and increments on each reload.
Block node configuration watcher started
CN is now watching the file for future changes.
Block node connection manager started
Connection manager is active.
[HOST:PORT] Block node is available for streaming (wantedBlock: N)
CN reached the BN's status API and confirmed it is ready.
Selected new block node for streaming: HOST:PORT (wantedBlock: N)
Active streaming connection established.
If you see instead:
Streaming is not enabled; block node connection manager will not be started
blockStream.writerMode is FILE. Change it to FILE_AND_GRPC or GRPC.
Block node configuration file does not exist at PATH
block-nodes.json is missing or in the wrong directory. Check blockNode.blockNodeConnectionFileDir.
No block nodes available for streaming
CN cannot reach any listed Block Node. Check network connectivity and firewall rules on port 40840.
On the Block Node
Once the CN is streaming, the Block Node metric blocknode_publisher_block_items_received_total will begin incrementing. Monitor it via the Block Node metrics endpoint (default port 16007) or via Grafana.
A steadily increasing value confirms the Block Node is receiving blocks from the CN. A value of 0 or no metric present means the CN has not yet established a streaming connection.
See Block Node Metrics for the full metrics reference and Block Node Troubleshooting if the connection does not establish.
Optional — Tune connection behaviour
The following blockNode.* settings in the CN's application.properties control how the CN manages Block Node connections. The defaults are appropriate for most deployments.
blockNode.streamResetPeriod
24h
How often the CN proactively resets its streaming connection. Periodic resets prevent long-lived connections from drifting.
blockNode.highLatencyThreshold
30s
Block acknowledgement latency above which the CN considers the connection high-latency.
blockNode.highLatencyEventsBeforeSwitching
5
Number of consecutive high-latency acknowledgements before the CN considers switching to another Block Node.
blockNode.globalCoolDownSeconds
10
Minimum time in seconds between connection switches, regardless of cause.
blockNode.grpcOverallTimeout
30s
gRPC client connection timeout.
Troubleshooting
blocknode_publisher_block_items_received_total stays at 0 after setup
The CN has not established a streaming connection. Any of the three causes below may apply.
Check the CN logs for the error messages listed in Step 3. Confirm blockStream.writerMode is not FILE and block-nodes.json is present in the correct directory.
CN log: Streaming is not enabled; block node connection manager will not be started
blockStream.writerMode is set to FILE.
Set blockStream.writerMode=FILE_AND_GRPC in application.properties and restart the CN.
CN log: Block node configuration file does not exist at PATH
block-nodes.json is absent or in the wrong directory.
Create the file at the path shown in the log, or set blockNode.blockNodeConnectionFileDir to the directory that contains the file.
CN log: No block nodes available for streaming
The CN cannot reach any Block Node listed in block-nodes.json — either the address/port is wrong or a firewall is blocking the connection.
Verify the address and streamingPort values in block-nodes.json. Run nc -vz <address> <streamingPort> from the CN host. Open TCP port 40840 inbound on the BN host if the test fails.
nc -vz <BN_HOST> 40840 fails from the CN host
Port 40840 is blocked between the CN and BN hosts.
Check host firewall rules on both the CN and BN hosts. Open TCP inbound on port 40840 on the BN host. If running in Kubernetes, check network policy and security group rules.
The address in block-nodes.json resolves to the wrong host or not at all
The hostname is not resolvable from the CN host's DNS.
Run nslookup <address> or dig <address> from the CN host. Use an IP address instead of a hostname if DNS resolution is unreliable.
CN logs show a successful connection but the BN still shows blocknode_publisher_block_items_received_total at 0
The CN connected to the servicePort (status API) but may be streaming to the wrong streamingPort, or the BN's publisher plugin is not loaded.
Confirm streamingPort in block-nodes.json matches the port the BN's publisher plugin listens on (default 40840). Check the BN logs for publisher plugin startup messages.
block-nodes.json was updated but the CN did not reload the configuration
Some editors replace files atomically (write to a temp file then rename), which may not trigger the inotify create event the CN watches for.
Check CN logs for file-watcher errors. If the reload did not fire, delete the file and recreate it — the CN also watches for create events and will reload on the new file.
The CN frequently switches between Block Nodes
The primary Block Node's acknowledgement latency is exceeding blockNode.highLatencyThreshold (30s by default) on consecutive blocks.
Check Block Node performance (CPU, memory, disk I/O). Increase blockNode.highLatencyEventsBeforeSwitching to tolerate more high-latency events before switching. See Block Node Troubleshooting.
Last updated