Troubleshooting
Common errors and how to fix them
HederaNetworkNotConfiguredException
The
Fix: Confirm the spelling matches exactly (
The
network value on an operation (or Hedera:DefaultNetwork) doesn't match
any key under Hedera:Networks in appsettings.
Fix: Confirm the spelling matches exactly (
mainnet/testnet/previewnet, case-sensitive), or add the missing entry — see Networks.
Invalid account/token/topic ID format
Hedera IDs follow the
Fix: Run
Hedera IDs follow the
shard.realm.num pattern (e.g. 0.0.98). A malformed ID
(missing a segment, non-numeric, wrong shard/realm) is rejected before or by the Mirror Node.
Fix: Run
utility.validateAddress (see Utility Operations) on any user-supplied ID before using it in another call.
Mirror Node rate limiting (HTTP 429)
The public Mirror Node endpoints are shared infrastructure and rate-limit heavy callers.
Fix: Back off and retry with exponential delay; avoid tight polling loops with a
The public Mirror Node endpoints are shared infrastructure and rate-limit heavy callers.
Fix: Back off and retry with exponential delay; avoid tight polling loops with a
topic.getMessages interval under a few seconds. Consider caching token.getInfo
results client-side — token metadata rarely changes.
"Transaction not found" right after submitting it
The Mirror Node indexes a few seconds behind live consensus. Calling
Fix: Add a short delay (2-5 seconds) or a small retry loop before the first
The Mirror Node indexes a few seconds behind live consensus. Calling
transaction.get immediately after submission can return not-found even though the
transaction succeeded.
Fix: Add a short delay (2-5 seconds) or a small retry loop before the first
transaction.get call following a submission.
Garbled or truncated HCS message content
This usually means the topic carries binary data but
Fix: Set
This usually means the topic carries binary data but
decodeUtf8 was left at its default
(true).
Fix: Set
decodeUtf8: false on topic.getMessages and
decode the returned base64 yourself, using whatever encoding the publisher actually used.
Attempting a write operation
Account transfers, token mint/associate/transfer, and topic create/submit are not yet implemented on this node — every current operation is a Mirror Node read.
Fix: See Roadmap for what's planned and why it isn't here yet.
Account transfers, token mint/associate/transfer, and topic create/submit are not yet implemented on this node — every current operation is a Mirror Node read.
Fix: See Roadmap for what's planned and why it isn't here yet.