Waku topic filter subscriptions stop matching after upgrading past v0.24

What changed at v0.24

Based on the available research notes (model knowledge, not live documentation), v0.24 replaced the simple prefix-style filter syntax — a bare string such as a topic prefix — with a structured JSON filter expression that explicitly names the matching criteria (topic, and optionally author/content fields). Subscriptions still using the old string form are no longer parsed as valid filters, so the node treats them as rejected rather than as "match everything." That is why unchanged publisher code and topic names stopped delivering: the subscription side silently fails to register a usable filter.

Treat this as the likely explanation, not a confirmed fact, until you check the release notes for your exact versions — the precise field names in the JSON filter should be taken from the v0.24+ API reference for your client (js-waku, nwaku, or go-waku may expose it differently).

Mapping old filters to the new form

The canonical mapping described in the research is mechanical: take the old prefix string and place it in the filter's topic field, leaving the other criteria empty or at their defaults. Conceptually:

// pre-v0.24
subscribe("/myapp/1/notifications")

// v0.24+ (shape is illustrative — confirm field names in your client docs)
subscribe({ topic: "/myapp/1/notifications" })

Two cautions when doing this mapping across a fleet:

• Topic strings containing characters that need JSON escaping (quotes, backslashes) must be escaped properly; a naive string interpolation into a JSON template can produce an invalid filter that fails the same way as the old syntax.
• Apply the mapping in one shared helper rather than at each call site, so the transition is reversible from a single place.

Mixed-version interoperability

The filter expression is evaluated on the subscribing/receiving side, so interoperability depends on whether each subscriber understands the syntax it is given. A pre-v0.24 node handed the new JSON form will not recognize it and — per the research notes — will effectively ignore the subscription, causing silent delivery loss. Publishers are less sensitive: a message published on a topic is just a message; it is the subscription filter that changed.

The practical consequence: you do not need a flag-day upgrade of publishers, but you do need every subscriber to be on a version that understands the filter form you send it. The safest transition order is:

1. Upgrade subscriber nodes to v0.24+ first, keeping the old filter strings if your client still accepts them in a compatibility mode (verify this — do not assume it).
2. Switch subscription call sites to the JSON form via the shared helper.
3. Retire pre-v0.24 nodes last; until then, do not send them new-format filters.

If your client offers no compatibility shim, the fallback during transition is to run old nodes with a broad subscription and do application-level filtering, accepting the extra bandwidth temporarily rather than losing messages.

Distinguishing "filter rejected" from "no matching publisher"

The research notes indicate the implementation logs a distinct filter rejected event when a subscription's filter cannot be parsed, versus a no match-style outcome when the filter is valid but message criteria are not satisfied. Exact log strings and metric names vary by implementation, so grep your node logs around subscription time rather than at publish time — a rejected filter fails at subscription registration, which is the strongest signal:

# scoped example: watch subscription-time errors on one node
journalctl -u nwaku -f | grep -iE 'filter|subscri'

If the rejection appears at subscribe time, the syntax is the problem. If subscription succeeds and nothing arrives at publish time, look at topic naming or content criteria instead.

Verification plan

Your planned two-node test is the right shape. Run it as a 2×2 matrix — old filter vs. new filter, pre-v0.24 subscriber vs. v0.24+ subscriber — and record which combinations deliver. Expect: new filter + new node delivers; old filter + new node either errors at subscribe time or delivers nothing; any new-format filter sent to an old node is ignored. That matrix also tells you definitively whether a compatibility mode exists, which determines your migration order above.

One missing detail that changes the recommendation: which Waku client (nwaku, js-waku, go-waku) and exact versions you run, since field names, log strings, and any legacy-syntax shim are client-specific. Check that client's v0.24 changelog before finalizing the mapping helper.