When an NMOS node, registry, or route doesn't behave as expected, the fastest path is usually to work outward from where the chain actually breaks: can Buttons see the thing at all, can it reach it, and does the specific action (a route, an activation, an address assignment) actually complete.
Read the NMOS Logs first#
Connection → NMOS has its own NMOS Logs panel, filterable by Error, Warn, Info, Verbose, and Debug, the same pattern used by a regular connection's own logs. Most of the problems below leave a specific message here before they show up as a stuck UI state.
Discovery problems#
If nodes never appear at all, the issue is usually discovery reach rather than adoption:
- Confirm Enable NMOS Controller mDNS listening is on under Settings → NMOS, if the node is expected to announce itself on the local network.
- Confirm Enable NMOS Controller DNS-SD listening is on if your network uses DNS-SD search domains instead of, or alongside, mDNS. This is common when nodes and Buttons aren't on the same broadcast segment.
- Check P2P node adoption mode: set to Do not adopt, discovered peer-to-peer nodes stay visible in Discovered nodes but are never automatically turned into connections; set to Adopt all, they're adopted as soon as they're seen.
- If a previously adopted peer-to-peer node stops being seen, check When a P2P node is no longer seen: Do nothing leaves its connection as-is, Disable Connection disables it automatically, and Delete Connection removes it: this explains a connection disappearing or going disabled without anyone touching it directly.
Registry connectivity problems#
A Registry connection's own status dot tells you where it's stuck:
- Disabled: the connection itself is turned off.
- Connecting... or Waiting for runtime...: Buttons hasn't finished establishing the connection yet; give it a moment before assuming a failure.
- A status showing a specific message while otherwise healthy or unhealthy: read the message itself; it's surfaced directly from the registry client.
If Buttons can't identify a registry at all, look for a log message like "Unable to identify NMOS Registry: no Query API endpoint responded successfully": this means every configured or discovered endpoint failed to respond, not that one endpoint alone is unreachable. Confirm the registry is actually running and that Buttons' network can reach at least one of its endpoints.
A registry connection that keeps failing and retrying logs a "Registry connection runtime setup failed; retrying" warning: this is Buttons retrying on its own; persistent retries point to a registry that's reachable at the network level but rejecting or erroring on requests, rather than a simple connectivity gap.
If nodes aren't being adopted the way you expect from a registry, check Registry adoption strategy under NMOS Controller discovery: this ranges from Only manual adoption (nothing happens automatically) through Use Internal Registry, to mDNS- or DNS-SD-based strategies that either pick one registry with fallback priority or create an individual connection per discovered registry. A strategy that doesn't match what you expected explains adoption behavior that looks inconsistent across registries.
Node status problems#
A node connection's own status dot follows a similar pattern: Disabled, Node unavailable (the adopted node no longer exists in the registry it came from), Loading..., Waiting for runtime..., or a specific message while fetching: read that message when it's shown, since it's surfaced directly from the node.
- Fetching Initial State on a node in the connection list means Buttons adopted it but hasn't finished loading its NMOS data yet.
- No NMOS Data found with a Retry button appears for a peer-to-peer node whose data never arrived: select Retry to ask Buttons to fetch it again.
- The equivalent state for a registry-adopted node has no Retry button, since that data has to come from the registry itself: the description "Waiting for data from registry. Data will appear once the registry provides it" means the registry hasn't reported this node's resources yet, not that Buttons is stuck.
A disabled node connection shows a callout on its own page: "This node connection is currently disabled. Enable it to start using this connection."
Route and endpoint failures#
A route to or from an NMOS resource goes through the same
routing report as any other connection. Look for these NMOS-specific causes inside a failed request:
- A staging request rejected as invalid, or a response Buttons couldn't parse: these point to the receiver or sender rejecting the requested transport parameters, not a Buttons-side problem.
- An HTTP-level error reaching the sender or receiver's own IS-05 endpoint: this usually means the device itself is unreachable or refusing the request, separate from whether Buttons could see it through discovery.
SDP and activation failures#
If Activate Sender when SDP Present never activates a sender, or a route depends on an SDP that never arrives, check for an SDP fetch failure in the logs: Buttons logs both attempts and failures per endpoint tried, so you can see exactly which address it couldn't read an SDP from before falling back to the next one.
Multicast assignment failures#
Multicast address problems have their own dedicated troubleshooting table in
Manage NMOS multicast addresses. In brief: a sender that never gets assigned an address usually means no configured profile matched its category, logged as a missing-matching-rule warning; a sender that fails partway through logs the specific assignment failure reason.
If you get stuck#
What you see | What to try |
|---|
A node never appears in discovery. | Check the relevant mDNS or DNS-SD listening toggle under Settings → NMOS, and confirm the node is actually announcing on a network Buttons can reach. |
A node appears but is never adopted. | Check P2P node adoption mode for peer-to-peer nodes, or Registry adoption strategy and Node adoption on the relevant Registry connection. |
A connection or node vanished or became disabled unexpectedly. | Check When a P2P node is no longer seen (peer-to-peer) or When a Node disappears (Registry connection): an automatic behavior may have acted on it. |
A Registry connection won't come online. | Look for an "Unable to identify NMOS Registry" message in NMOS Logs, and confirm at least one configured endpoint is reachable. |
A route fails against an NMOS sender or receiver. | Open the routing report for the specific staging or activation error, then confirm the device's own IS-05 endpoint is reachable. If the failure names an unsupported IS-05 version (for example, a device advertising v1.3+ when Buttons supports v1.0–v1.2), expand the report's "IS-05 endpoints" section for the versions and endpoints Buttons actually tried. |
A sender never activates automatically. | Confirm Activate Sender when SDP Present is on, and check NMOS Logs for an SDP fetch failure. |
Where to go next#
