Why Stellar RPC getEvents returns no events
Last updated:
At a glance
| Property | Value |
|---|---|
| Empty result | No event in range matched every filter |
| startLedger older than the node's window | An error, not an empty result |
| Filters | Up to 5; each with type, up to 5 contract IDs, topics as base64 ScVal |
| limit | 1 to 10,000; default 100 |
| Default retention window | 120,960 ledgers |
What you see
getEvents for a contract you know emits events returns an empty events list and a cursor, with no error. Removing the topic filter suddenly returns results.
Why this happens
Stellar RPC's getEvents reference defines startLedger as the "ledger sequence number to start fetching responses from (inclusive)" and says the method "will return an error if startLedger is less than the oldest ledger stored in this node, or greater than the latest ledger seen by this node" — so an empty list is not a retention problem. Events are matched by up to 5 filters; each has a type (contract or system), up to 5 contract IDs, and topics made of 1–4 segment matchers "encoded as base64 ScVal strings", with * matching one topic and ** the rest. A topic written as plain text or encoded as the wrong ScVal type matches nothing. Results are paged with a cursor and a limit of 1 to 10,000 (default 100). The default retention window is 120,960 ledgers.
What to do
- Run the query with only the contract ID to confirm the contract emitted events in the range.
- Encode each topic as the exact ScVal the contract emits, base64 XDR, and use * for positions you do not care about.
- Check the filter type (contract or system) and that the contract ID is the one on this network.
- Page with the returned cursor rather than widening startLedger; if you get an error about startLedger, the ledger is outside this node's window.
When this is not our problem
Filter matching and the retention window belong to Stellar RPC itself and behave the same on every Stellar RPC server, whoever operates it, Triport included.
FAQ
- Why does Stellar getEvents return an empty list?
- No event in the range matched your filters — most often a topic that is not encoded as base64 XDR ScVal of the right type, or the wrong contract ID.
- What happens if startLedger is too old?
- getEvents returns an error when startLedger is below the oldest ledger the node stores.