FAQ & Troubleshooting

Common Issues

1. Authentication errors:

   Failed to authenticate to APIC: ...

   Solution: Verify that APIC_URL, APIC_USERNAME, and APIC_PASSWORD are set correctly. Confirm you can reach the APIC REST API from your agent host by testing https://<apic-host>/api/aaaLogin.json with the same credentials.

2. Connection timeout:

   requests.exceptions.ConnectTimeout

   Solution: Check network connectivity from the agent host to the APIC. Verify that firewall rules allow outbound HTTPS (port 443) to the APIC address.

3. Interface query returns 503:

   Query to <path> returned too many objects (>100,000). Apply filters to reduce result set size.

   Solution: The APIC REST API has returned a "dataset too large" error, which occurs when the result set exceeds 100,000 objects. The integration does not retry this error. Use pod scope filtering (scope.pods) to reduce the result set size. Contact support@netboxlabs.com if you encounter this consistently.

4. 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.

5. Custom fields not present in NetBox after first run:

   Solution: The custom fields are created during bootstrap mode. Ensure you ran the agent with BOOTSTRAP: true and applied the resulting deviations in NetBox Assurance before running the full sync.

6. 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.

Frequently Asked Questions

Q: Does the integration write any data back to the Cisco APIC?

A: No. The integration is read-only. It queries the APIC REST API and sends discovered data to NetBox via Diode. No changes are made to the ACI fabric.

Q: Will objects be deleted from NetBox if they are removed from the ACI fabric?

A: No. The integration does not delete NetBox objects. If a device, interface, or other object is removed from the fabric, it will not be automatically decommissioned in NetBox. You must handle decommissioning manually.

Q: Can I run the integration against multiple ACI fabrics?

A: Yes, by running a separate agent instance for each fabric. Each instance is configured with its own APIC_URL, APIC_USERNAME, and APIC_PASSWORD, and should use a distinct agent_name and SITE_NAME to keep fabric data separate in NetBox.

Q: Can I filter the sync to a specific tenant or pod?

A: Yes. Use the scope section of your policy configuration to restrict ingestion to specific tenants or pods. See Scope Parameters for the configuration syntax. VRF-level scope filtering is not supported - VRFs are always synced for the configured tenants.

Q: Why do some interfaces show a generic type like 1000base-x-sfp when the actual optic is different?

A: Interface type is resolved using a three-tier chain. First, the integration queries ethpmFcot for the transceiver hardware model (for example, QSFP-100G-SR4-S) and maps it to the correct NetBox type. If no transceiver data is available, it falls back to the negotiated operational speed from ethpmPhysIf. If neither source returns usable data - for example when an interface is administratively down or unpopulated - it falls back to 1000base-x-sfp. See Interface Type Mapping for the full mapping tables.

Q: What happens if the same gateway IP appears on multiple leaf switches (anycast gateway)?

A: The integration handles anycast gateways by creating a single IP address entry in NetBox and tracking all associated SVI interfaces in the aci_gateway_interfaces_json custom field on that IP address object.

Q: How do I change the NetBox site name for my fabric?

A: Set the SITE_NAME parameter in your agent.yaml configuration. The default value is "ACI Fabric". Run bootstrap mode again after changing this value to ensure the site entity is re-created with the new name.