FAQ & Troubleshooting

Common Issues

Authentication errors:
```
Either CVP_API_TOKEN or both CVP_USERNAME and CVP_PASSWORD must be provided
```
Solution: Provide either CVP_API_TOKEN, or both CVP_USERNAME and CVP_PASSWORD, in your configuration or .env file. A service account token is the recommended method.
Session token exchange fails:
```
Fatal error running Arista CloudVision integration backend: Authentication failed at cvp.example.com: <error>
```
Solution: When using username/password authentication, verify the credentials are correct and that the account can reach the CloudVision REST login endpoint. Confirm CVP_HOST is correct and reachable from the agent host.

Invalid host errors:

Invalid host 'https://cvp.example.com': do not include a URL scheme (use 'cvp.example.com', not 'https://cvp.example.com')

Invalid host 'cvp.example.com/cvp': expected 'hostname' or 'hostname:port', e.g. 'cvp.example.com' or 'cvp.example.com:443'

Solution: Set CVP_HOST to a bare hostname or hostname:port (for example, cvp.example.com or cvp.example.com:443). Do not include a scheme such as https://, a path, or credentials.

CVP_HOST is not the CloudVision gRPC endpoint:
```
Connected to cv-prod-us-4.arista.io:443, but it did not respond as a CloudVision gRPC endpoint. Check CVP_HOST: CVaaS clusters are addressed as www.<cluster>.arista.io.
```
Solution: For CVaaS, set CVP_HOST to www.<cluster>.arista.io (for example, www.cv-prod-us-4.arista.io). The cluster hostname shown in your browser, without the www. prefix, is not the gRPC endpoint. For on-premises CVP, check that CVP_HOST names the CloudVision server.
TLS certificate errors:
```
username/password auth cannot be used with ssl_verify=False: credentials would be sent over an unverified TLS connection. Use api_token instead, or set ssl_verify=True.
```
Solution: Setting CVP_SSL_VERIFY=False accepts a self-signed certificate but requires CVP_API_TOKEN, and the certificate must be issued for CVP_HOST. It cannot be used with username/password authentication, which produces the error above. See TLS verification.
Diode connection errors:
```
failed to connect to diode
```
Solution: Verify that DIODE_CLIENT_ID, DIODE_CLIENT_SECRET, and the target value in your agent.yaml are correct. Confirm outbound gRPCS access (port 443) from your agent host to your NetBox instance.
A scoped run ingests no devices or fails on the tag API:

Solution: When scope.sites or scope.tags is set, the integration must be able to read CloudVision device tags. If the tag API is unavailable or the token lacks tag-read permission, a scoped run fails deliberately rather than silently ingesting nothing. Confirm the token can read tags, or remove the scope filter to run with the site and role fallbacks.
CVP_HOST is missing:
```
CVP_HOST must be provided in policy config
```
Solution: Set CVP_HOST in your configuration or .env file, and make sure the variable is passed to the agent container. The run sends nothing to NetBox until it is set.
The run fails reading the inventory or tags:
```
Fatal error running Arista CloudVision integration backend: Inventory fetch failed: <error>
```
Solution: The first calls of a run read the device inventory and tags. A failure here usually means the token is invalid or has expired, or the account cannot read the inventory. Check the token or credentials, and that CVP_HOST is reachable. A tag read failure on a scoped run is reported as Tag assignment fetch failed: <error>.
A warning says the tag API is unavailable:
```
Tag API unavailable, proceeding without CVP tags (site and role fallbacks will apply, global-table IPAM suppressed this run): <error>
```
Solution: On an unscoped run, the integration continues without device tags: devices get the SITE_NAME site and the fallback role, and global-table addresses and prefixes, VLANs, and VLAN groups are not sent this run. Confirm the account can read device tags.
A warning says an address is skipped:
```
Skipping invalid IP <address> on <device>/<interface>: <error>
```
Solution: The address in the running configuration could not be read as an address with a prefix length, for example ip address dhcp. The interface is still recorded, without that address.
A scope filter is not a list:
```
Fatal error running Arista CloudVision integration backend: scope.sites must be a list, got str. Value: London
```
Solution: Write scope.sites and scope.tags as YAML lists, for example sites: ["London"]. The same error is reported for scope.tags. See scope Parameters.
Custom fields not present in NetBox after the first run:

Solution: The custom fields are created during bootstrap mode. Ensure you ran the agent with BOOTSTRAP: true before running the full sync. On NetBox Cloud and NetBox Enterprise 2.3.0 and later, the custom fields are created directly. On NetBox Enterprise before 2.3.0, also apply the resulting deviations in NetBox Assurance.

Objects not appearing in NetBox after the agent reports successful ingestion:

Solution: Discovered data is staged as deviations in NetBox Assurance and must be applied before it appears in NetBox. Navigate to Assurance → Active Deviations and apply the deviations.

Devices sync, but no interfaces, VLANs, VRFs, prefixes, or IP addresses appear:
```
Config fetch for <serial> failed with <STATUS>: the compliance API is not usable with these credentials; skipping the remaining N devices (config-derived entities degraded this run): <error>
```
Solution: Layer-3 objects are parsed from each device's running configuration, which is read through the CloudVision compliance API. This warning means the API rejected the request because the CloudVision version does not provide it, the credentials cannot access it, or the token is invalid or has expired. Confirm the service account or user can read device running configurations. Device-level data continues to sync in the meantime.
Some devices have no interfaces or addresses:
```
Retrieved running configs for 10/12 devices
```
Solution: Running configurations are fetched per device, and a device whose configuration cannot be read is skipped with a warning naming its serial number, for example Skipping config for <serial>: ..., Config fetch failed for <serial> ..., or Skipping device <serial>: running config failed to parse: .... Check that the device is streaming to CloudVision. The device's other data still syncs, and its layer-3 objects are added on the next run that reads its configuration.
Observations incomplete warning in the log:

Solution: Not every in-scope device produced a usable running configuration this run. To avoid writing conclusions that a missing device could contradict, the integration withholds some IP address interface assignments and prefix site scopes until a run reads every device. See Configuration Retrieval and Partial Runs.

Frequently Asked Questions

Q: Does the integration write any data back to Arista CloudVision?

A: No. The integration is read-only. It reads the CloudVision inventory, tag, and compliance APIs and sends discovered data to NetBox via Diode. No changes are made to CloudVision.

Q: Can I use the integration to push data from NetBox into CloudVision?

A: No. Data flows from CloudVision into NetBox only. The integration does not provision or configure anything in CloudVision.

Q: Will objects be deleted from NetBox if they are removed from CloudVision?

A: No. The integration does not delete NetBox objects. If a device is removed from CloudVision, it is not automatically decommissioned in NetBox. The same applies to interfaces, VLANs, VRFs, prefixes, and IP addresses removed from a device's configuration. Handle these removals manually.

Q: Does the integration work with both CloudVision Portal (CVP) and CloudVision as a Service (CVaaS)?

A: Yes. Both are reached over the CloudVision gRPC Resource API on port 443. For CVaaS, set CVP_HOST to www.<cluster>.arista.io.

Q: Can I run the integration against multiple CloudVision systems?

A: Yes. Add a policy for each system, each with its own CVP_HOST, credentials, and a distinct CVP_NAME so its objects are identifiable by the cv-{name} tag in NetBox.

Q: How is a device's NetBox site determined?

A: The site is resolved from the device's topology_datacenter CloudVision system tag. When that tag is absent, the device is assigned to the SITE_NAME value (default "CloudVision").

Q: How is a device's NetBox role determined?

A: The role is resolved from the device's topology_type CloudVision system tag - for example spine, leaf, l2leaf, superspine, campus-leaf, or borderleaf. Values are matched exactly and are case-sensitive. A device with no topology_type tag, or an unrecognized value, is assigned the Network Switch fallback role.

Q: Why do some devices have the device type Unknown Device, Wireless Access Point, or Arista EOS Switch?

A: These are placeholders for devices where CloudVision reports no hardware model, which is common for access points and third-party devices. Access points are identified by their topology_type tag and get Wireless Access Point. Other devices that report an EOS release version, such as 4.32.1F, get Arista EOS Switch, and the rest get Unknown Device, including third-party devices that report their own version, such as NX-OS 10.3(4a). Devices under the Unknown manufacturer get no platform. Placeholders that cannot be attributed to Arista use an Unknown manufacturer. See Device type resolution.

Q: Where does the management interface name come from?

A: From the device's running configuration, so it matches the device. Only when no device's configuration could be read in a run does the integration name the management interface from the hardware model instead: Management0 for chassis families, Management1/1 for a few specific models, and Management1 for everything else. See Management interface naming.

Q: Are interfaces, VLANs, VRFs, prefixes, and IP addresses synchronized?

A: Yes. They are parsed from each device's EOS running configuration, retrieved through the CloudVision compliance API. See Running Configuration Parsing for what is read.

Q: Why are some VLANs missing?

A: Only single-VLAN stanzas such as vlan 10 are parsed. VLANs declared as a range or list, such as vlan 10-20 or vlan 10,20,30, are not created in this release. A VLAN used on a port but not declared in a vlan stanza is also not linked to the port.

Q: Is VXLAN supported?

A: Not in this release. Vxlan* interfaces are created, but VNI-to-VLAN mappings and VTEP source interfaces are not parsed.

Q: What are the cv-site-* VRFs?

A: When your devices span more than one site, the integration places each site's global routing table addresses and prefixes in a synthetic cv-site-{site} VRF. This keeps address ranges reused across sites, such as loopbacks, as separate NetBox records. Their route distinguishers are generated by the integration and do not exist in your network. Single-site deployments create none. See Multi-site VRF separation.

Q: Why does an IP address have no interface assignment?

A: Either the address is configured on more than one interface in the same routing domain, or it is an ip address virtual shared gateway, which is created with the anycast role. In both cases no single interface owns it, and the integration logs a warning naming the interfaces that claim it. An address can also be left unassigned for one run when not every device's configuration was read.

Q: Why does a device have no primary IP?

A: A device's primary IP is set from its management interface address. When that address is claimed by more than one interface in the same routing domain (in a multi-site deployment, the same site), NetBox cannot assign it to one device, so the device gets no primary IP, and the integration logs a warning beginning IP <address> is a management address on <device> but is claimed by more than one interface.

Q: Why was a value I set by hand removed?

A: The integration clears some fields when the running configuration shows they no longer apply: an interface's VRF and switchport mode, an IP address's interface assignment, a prefix's site scope, and a device's primary IP. It also clears the platform of a device under the Unknown manufacturer that reports a version. A manual value on one of these fields of a CloudVision-managed object is removed on the next sync. To keep a hand-set platform, ignore the proposed change in NetBox Assurance.

Q: How do I change the fallback NetBox site name?

A: Set the SITE_NAME parameter in your configuration. The default is "CloudVision". This value is only used for devices that have no topology_datacenter tag.

Common Issues

Frequently Asked Questions

On this page