FAQ & Troubleshooting

Frequently asked questions

Is the integration free to use?

The Cisco Nexus Dashboard integration is available with commercial editions of NetBox (NetBox Cloud and NetBox Enterprise).

Do I need NetBox Assurance?

Yes. The integration extracts and transforms the latest state from Nexus Dashboard and sends it to NetBox Assurance, where you control how it is ingested into NetBox.

Which Nexus Dashboard versions are supported?

Nexus Dashboard 4.x, through the unified Manage API (/api/v1/manage/). The integration was validated live against 4.2.1. On 4.1.x everything syncs except interfaces and interface-assigned IP addresses, because the per-switch interface endpoint does not exist on that version.

The legacy per-service NDFC and Nexus Dashboard Orchestrator APIs that 4.x replaced are not supported.

Which NetBox editions are supported?

NetBox Cloud and NetBox Enterprise, with NetBox Assurance.

Does the integration write anything back to Nexus Dashboard or to my switches?

No. Apart from the login request, every call it makes is a GET. Data flows one way only, from Nexus Dashboard into NetBox.

What permissions does the Nexus Dashboard account need?

Read access to fabric inventory through the Manage API. The integration only issues GET requests against the fabrics, switches, interfaces, VRFs, and networks endpoints, so it needs no write, modify, or delete permission anywhere on the cluster.

Where do my Nexus Dashboard credentials go?

Into the policy config block, as ND_USERNAME and ND_PASSWORD or as ND_API_KEY and ND_API_USERNAME. Reference them with ${...} substitution so the agent replaces them with environment variables from its own process when it loads the policy, rather than storing the secret in the file. You run the agent and you hold the credentials; nothing about them is stored in NetBox.

Can I authenticate with an API key instead of a username and password?

Yes. Set ND_API_KEY and ND_API_USERNAME - both are required together. They are sent as the X-Nd-Apikey and X-Nd-Username headers, no login call is made, and there is no token to refresh. API key authentication takes precedence if you supply both credential pairs.

What is ND_LOGIN_DOMAIN for?

It selects which Nexus Dashboard login domain authenticates your username and password - for example a remote LDAP, RADIUS, or TACACS domain rather than the local one. The value is the domain name as listed by GET /logindomains on your cluster, and it is case-sensitive. Omit the key to use the cluster's configured default login domain. It has no effect with API key authentication.

Does the integration discover the Nexus Dashboard cluster nodes themselves?

No. Only fabric switches are modeled as NetBox devices. The controller and cluster nodes are not emitted.

Will objects be deleted from NetBox if they are removed from Nexus Dashboard?

No. The integration does not delete NetBox objects. A switch removed from a fabric is not automatically decommissioned in NetBox - handle decommissioning manually.

How is a switch's NetBox site determined?

From its fabric. Each Nexus Dashboard fabric becomes one NetBox site, named after the fabric's name field, and every switch, VLAN, and prefix in that fabric is scoped to it.

How is a switch's NetBox role determined?

From its switchRole value: leaf, spine, border, border_gateway, border_spine, and access map to named roles with colors. A value the integration does not recognize is passed through verbatim as the role name, without a color, rather than being dropped. A switch with no switchRole is assigned the Unknown role. See Device role mapping.

Only the roles your discovered switches actually use are created in NetBox.

Can I limit which fabrics are synchronized?

Yes. Set scope.fabrics to a list of fabric names in the policy scope block, separate from config. Names are matched exactly against each fabric's name field, so they are case-sensitive. Omit the key, or use ["*"], to sync every fabric on the cluster.

Can I run the integration against multiple Nexus Dashboard clusters?

Yes, by running a separate agent instance for each cluster. Give each its own ND_HOST, credentials, and a distinct agent_name. Each cluster's objects are tagged nd-{host}, derived from ND_HOST, so they remain identifiable in NetBox.

What are the nd_switch_db_id and nd_segment_id custom fields?

nd_switch_db_id holds each switch's internal Nexus Dashboard database identifier. nd_segment_id holds each overlay network's VXLAN VNI, or segment ID. Both are created in bootstrap mode and are read-only in the NetBox UI.

Does the integration create NetBox Tenants?

No. Fabric grouping is expressed through sites, and cluster grouping through the nd-{host} tag, so the integration does not impose a tenant structure on your NetBox data.

Why does my VRF's route distinguisher include the fabric name?

Because Nexus Dashboard allocates vrfId from a per-fabric pool, so two fabrics routinely hold different VRFs under the same ID. Diode matches VRFs on the route distinguisher whenever it is set, so a fabric-independent RD would merge two distinct VRFs into a single NetBox object. Including the fabric name keeps them separate.

Why does my VRF's route distinguisher contain a ~ and a string of hex characters?

NetBox limits a route distinguisher to 21 characters. When your fabric name and VRF ID together exceed that, the fabric name is truncated and a ~ plus the first 8 characters of its SHA-256 digest are appended in its place, so the result still fits. A fabric named a-very-long-fabric-name holding VRF ID 150001 yields the RD a-ver~70bcbb17:150001. The digest keeps the RD unique and stable across runs while the surviving prefix keeps it readable.

Are overlay VLANs, prefixes, and IP addresses synchronized?

Yes. Overlay networks become NetBox VLANs carrying their VXLAN VNI, their gateway subnets become prefixes, and their gateway addresses are emitted as anycast IP addresses. Management, loopback, and routed interface addresses are also synced from interface data.

Common issues

ND_HOST is missing from the policy config:
```
ND_HOST must be provided in policy config
```
Solution: Set ND_HOST in the policy config block to your cluster's base URL, including the scheme - for example https://nd.example.com. The run ends without ingesting anything. A value that is present but blank is treated the same as absent, so check whether a ${ND_HOST} reference resolved to an empty string.
Neither credential pair is complete:
```
Either (ND_API_KEY + ND_API_USERNAME) or (ND_USERNAME + ND_PASSWORD) must be
provided in policy config
```
Solution: Supply both halves of one pair. A common cause is one of two ${...} references resolving while the other does not - if the environment variable behind a reference is not set at all, the literal text is passed through, and if it is set to an empty value the key reads as absent. This check runs before any request is made, so it fails as a configuration error rather than a network error.
Nexus Dashboard rejected the credentials:
```
Fatal error running Nexus Dashboard backend: 401 Client Error: Unauthorized for
url: https://nd.example.com/api/v1/infra/login
```
Solution: Verify the username and password, and whether the identity belongs to a remote login domain. If it does, set ND_LOGIN_DOMAIN to that domain's name exactly as GET /logindomains reports it - the value is case-sensitive. A ${...} reference whose environment variable was never set will also produce this, because the literal ${ND_PASSWORD} text is sent as the password.

For API key authentication, confirm that ND_API_KEY and ND_API_USERNAME are both correct and that the key has not been revoked.
TLS certificate verification failed:

The run fails with a certificate verification error naming your Nexus Dashboard host. The exact wording comes from the underlying TLS library, not from the integration.

Solution: Nexus Dashboard clusters commonly present a certificate signed by an internal CA. Add that CA chain to your agent host's trust store, which is the right fix for production. For initial testing you can set SKIP_SSL: true in the policy config, but this disables verification for every request including the login request that carries your password, so use it only on a trusted network.
Login succeeded but returned no token:
```
Nexus Dashboard login succeeded but no jwttoken returned in response
```
Solution: The cluster accepted the login but the response carried no jwttoken value. Confirm that ND_HOST points at a Nexus Dashboard 4.x cluster and not at a proxy, load balancer, or captive portal that intercepted the login response. Try API key authentication to confirm the rest of the configuration is sound.
The fabric list could not be fetched:
```
Fatal error running Nexus Dashboard backend: ...
```
followed by a traceback naming /api/v1/manage/fabrics.

Solution: A failure listing fabrics aborts the run deliberately, because an error cannot be distinguished from a cluster with no fabrics - continuing would report a successful sync of nothing. Check network reachability to ND_HOST, and that the identity is permitted to read the Manage API.
One fabric's data could not be fetched:
```
Failed to fetch switches for fabric 'evpn-lab': ...
Failed to fetch VRFs for fabric 'evpn-lab': ...
Failed to fetch networks for fabric 'evpn-lab': ...
```
Solution: These are warnings, not failures. That collection is treated as empty and the run continues with the remaining fabrics and data types. Check the error text for the underlying cause - a timeout, a permission denial, or an HTTP error from the cluster. Data for the affected fabric will be incomplete until the next successful run.
No interfaces or interface IP addresses appear in NetBox:
```
Failed to fetch interfaces for switch FDO12345678: ...
```
Solution: If your cluster runs Nexus Dashboard 4.1.x, this is expected - the per-switch interface endpoint does not exist on that version, so interfaces and interface-assigned IP addresses are skipped. Everything else still syncs, and each device still receives a primary IP from its fabricManagementIp, emitted as a /32. Upgrade to 4.2.x for interface discovery. On 4.2.x, check the error text for a per-switch failure; that switch's device, device type, platform, and role are unaffected.
A switch is missing from NetBox:
```
Skipping switch with missing serial, name, or model in fabric 'evpn-lab':
serial='FDO12345678' name='' model='N9K-C9300v'
```
Solution: A switch must report a serialNumber, a hostname, and a model to become a NetBox device. The warning names which values were empty. This usually means the switch is not fully discovered in Nexus Dashboard - check its state there.
A device's status is not being set in NetBox:
```
Unmapped discoveryStatus 'migration' for switch FDO12345678 — leaving status unset
```
Solution: The integration maps only the discoveryStatus values it has confirmed - ok, unreachable, and inProgress. Anything else leaves the NetBox status field untouched rather than guessing, so a status you set in NetBox yourself is never overwritten by a transient Nexus Dashboard state. Report the value in the warning to support@netboxlabs.com so the mapping can be extended.
An IP address has no interface assignment, and its device has no primary IP:
```
IP 10.10.11.101/21 appears on 65 interfaces — omitting interface assignment
Management IP 10.10.11.101/21 on switch FDO12345678 is shared with another
interface — not setting primary_ip4
```
Solution: This is expected behavior, not a fault. Nexus Dashboard reports a switch's management address in operData.ipAddress for interfaces that have none of their own, including unnumbered layer-3 ethernet ports. When an address is genuinely shared across many interfaces it is synced once without an assignment, because emitting it per interface would create many NetBox objects for one host address. Set that device's primary IP manually in NetBox if you need one.
A fetched record count does not match the total the API reported:
```
/fabrics/evpn-lab/switches: fetched 48 of 52 records reported by the API
```
Solution: The integration follows the API's pagination links to completion, so a mismatch means the cluster reported a total it did not deliver. Re-run the policy; if the mismatch persists, capture the log and contact support@netboxlabs.com.
Fabric scope filtering is being ignored:
```
scope.fabrics should be a list, got str — ignoring filter, ingesting all fabrics
```
Solution: scope.fabrics must be a YAML list, not a single string or a comma-separated value. Write it as:
```
scope:
  fabrics:
    - evpn-lab
```
A non-list value disables the filter rather than failing the run, so every fabric is ingested.
The run completes but nothing is ingested:
```
No entities to ingest
```
Solution: Check the earlier log lines. The most common causes are a scope.fabrics list whose names do not match any fabric - matching is exact and case-sensitive - and a cluster with no fabrics configured. The line reporting how many fabrics were fetched and how many survived filtering is where a typo shows up.
Permission errors accessing the mounted directory:

The agent cannot read the config file or write dry-run output, and fails with a permission error naming the mounted path (for example /opt/orb/). The exact wording comes from the operating system, not from the integration.

Solution: Ensure the directory you mount with -v is readable, and writable if you use dry-run mode, by the agent container.

Support

Email support@netboxlabs.com for support.

Frequently asked questions

Common issues

Support

On this page