# Diagnose NMOS problems

> Work through discovery, registry, node, route, SDP, and multicast failures using the NMOS Logs and connection status indicators.

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:

1. Confirm **Enable NMOS Controller mDNS listening** is on under **Settings → NMOS**, if the node is expected to announce itself on the local network.
2. 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.
3. 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.
4. 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.

If a node is visible but never becomes usable, see [Discover, adopt, and route NMOS resources](/docs/buttons/v1.8/nmos/discover-and-adopt) for the adoption step itself.

## 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 registry-adopted node connection also reports how far it has got syncing that node from the registry:

| Status message | What it means |
| --- | --- |
| **Waiting for registry node sync** | The Registry connection hasn't started syncing this node yet. |
| **Syncing node from registry** | Buttons is fetching this node's resources from the registry. |
| **Node … is not listed by the registry; waiting for it to be announced** | The registry doesn't list this node right now. Buttons picks it up again as soon as the registry announces it. |
| **Registry node sync failed N times, retrying: …** | Fetching the node keeps failing. The text after **retrying:** is the reason; Buttons keeps retrying on its own. |

When a node leaves the registry, Buttons disables that node's ports, so a route to or from them is rejected straight away instead of failing partway through with "Could not find sender". The ports are enabled again when the node returns to the registry.

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](/docs/buttons/v1.8/routing/troubleshoot-a-route) 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](/docs/buttons/v1.8/nmos/multicast-auto-assignment#if-you-get-stuck). 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. |
| Adopting from a registry reports a node as skipped because it "is already adopted as a P2P node" or "through another registry". | The node already belongs to the named connection. Delete that connection first if you want this registry to own the node instead. |
| 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 registry-adopted node shows **Node … is not listed by the registry** and its ports are disabled. | The node has left the registry, or hasn't re-registered yet. Check the node itself and the registry it registers with: the ports come back on their own once the registry lists the node again. |
| 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

- [Troubleshoot a blocked or failed route](/docs/buttons/v1.8/routing/troubleshoot-a-route), for the routing report shared by every connection type.
- [Manage NMOS multicast addresses](/docs/buttons/v1.8/nmos/multicast-auto-assignment), for address-assignment-specific failures.