FAQ & Troubleshooting

Common Issues

Errors that stop the run are logged with the prefix Fatal error running Palo Alto Panorama integration backend:, followed by the error and a traceback.

PANORAMA_HOST is missing:
```
PANORAMA_HOST must be set
```
Solution: Set PANORAMA_HOST to Panorama's host name or address, and make sure the variable is passed to the agent container. The run sends nothing to NetBox until it is set.
Credentials are missing, or both credential paths are set:
```
Set PANORAMA_API_KEY, or PANORAMA_USERNAME with PANORAMA_PASSWORD
```
```
Set PANORAMA_API_KEY, or PANORAMA_USERNAME with PANORAMA_PASSWORD, but not both credential paths
```
Solution: Set either PANORAMA_API_KEY, or both PANORAMA_USERNAME and PANORAMA_PASSWORD, but not both paths. A username without a password counts as missing. The run sends nothing to NetBox until this is fixed.
PANORAMA_HOST is refused:
```
Fatal error running Palo Alto Panorama integration backend: PANORAMA_HOST must use https://
```
Solution: Panorama is always reached over HTTPS, so an http:// URL is refused. Set PANORAMA_HOST to a bare host, such as panorama.example.com, a host:port, or an https:// URL. The value must not contain spaces, a user name or password, a query, or a fragment.
Panorama refuses the credentials:
```
Fatal error running Palo Alto Panorama integration backend: Panorama refused the credentials (HTTP 403, PAN-OS code 403): API Error: Invalid Credential
```
Solution: The API key, or the username and password, is not valid for Panorama's XML API. Check the credentials, and that each ${...} variable in the configuration is set in the agent container's environment: an unset variable is sent as its literal text. Generate a new API key if the old one was revoked.
TLS verification fails when connecting to Panorama:

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

Solution: Panorama commonly presents a self-signed certificate or one signed by an internal CA. Add that CA to the agent host's trust store, or, for a lab Panorama, set PANORAMA_SSL_VERIFY: false.
SITE_FROM_HOSTNAME_REGEX is refused:
```
Fatal error running Palo Alto Panorama integration backend: SITE_FROM_HOSTNAME_REGEX must define a named group 'site', got '^([a-z]+)-fw'
```
Solution: The regular expression must name the part of the hostname that gives the site, as (?P<site>...). For example, ^(?P<site>[a-z]+)-fw takes lon from lon-fw01.
Panorama reports no hostname:
```
Fatal error running Palo Alto Panorama integration backend: Panorama reports no hostname. Set PANORAMA_NAME to name the instance
```
Solution: Set PANORAMA_NAME. Without it, the integration names the Panorama instance, and the default site, after the hostname Panorama reports. The error stops the run only when a firewall needs the default site. With SITE_NAME set, the run continues, without the panorama_instance field and the panorama-<name> tag.
A relayed call fails on a firewall:
```
Relayed call show system info failed on fw-branch-09 (serial 013101000043): PAN-OS code 13: 013101000043 not connected. The device is recorded from the inventory alone, without its management interface, its management addresses and its routing engine, and gets no further relayed call
```
Solution: The firewall did not answer through Panorama. The warning names the call and what the run does without it, and the rest of the run continues. PAN-OS code 13 means that the firewall is not connected to Panorama. Check the firewall's connection to Panorama. See Firewalls that do not answer.
Two firewalls appear as one device:
```
2 managed devices report the hostname PA-VM into site panorama-prod (serials 007954000918414, 007954000918418). NetBox treats them as one device. Rename all but one of them in Panorama
```
Solution: NetBox matches a device by its name and site before its serial number, so the two firewalls share one record, which alternates between them on every run. This is common for firewalls left at a factory hostname. Rename all but one in Panorama, and the next run separates them. See Device identity.
A firewall has no device group or template stack:
```
Managed device fw-branch-09 (serial 013101000043) is in more than one device group: branch, datacenter. It gets no device group field
```
Solution: The virtual systems of one firewall can sit in different device groups, so a firewall that two device groups list gets no panorama_device_group. A firewall that two template stacks list gets no panorama_template_stack or panorama_templates, with a similar warning. A device group in scope.device_groups still matches the firewall when any one of its groups is in scope.
No firewalls are synced with a scope:
```
scope.device_groups names device groups that Panorama does not report: brnach
```
```
The scope matches no managed device. The run records no device
```
Solution: Device group names must match Panorama's exactly. Check the names in scope.device_groups and the serial numbers in scope.serials. When both keys are set, a firewall must match both. See scope Parameters.
An interface has no MAC address:
```
Dropping the MAC address 00:50:56:00:00:01: it appears on more than one interface (pafw1 ethernet1/1, pafw2 ethernet1/1). A MAC address that is not unique would match another device's interface
```
Solution: This is expected. A MAC address is recorded only when exactly one interface in the run reports it, so that one firewall's interface cannot match another's. VM-Series firewalls commonly report the same MAC addresses as each other.
An IP address is recorded on only one interface:
```
Recording the address 10.1.1.1 of pafw1 in pafw1:default once, on ethernet1/1. Also reported by: ethernet1/2. One address in one VRF is one NetBox record
```
Solution: NetBox finds an IP address by its value within its VRF, so the address is recorded once, on the interface whose name sorts first. Check the firewall's interface configuration if the duplicate is not intended.
An interface has no VRF and no addresses:
```
Skipping the routing instance of pafw1 interface ethernet1/3: the forwarding domain 'vr:default' does not match the advanced routing engine. The interface is recorded without a VRF and without addresses for this run
```
Solution: The interface's routing instance does not match the routing engine the firewall reports: vr:<name> is expected on the classic engine, and logical-router:<name> on the advanced engine. The interface is still recorded. Its VRF and addresses are recorded on the first run in which its routing instance matches the engine. See Routing engine.
Interfaces have no description, MTU, or LAG:
```
Relayed call show config running on pafw1 (serial 007954000918414) names none of the interfaces that the device lists, although it lists an ethernet interface. The configuration may not have the shape that this integration reads. Its interfaces get no enabled, description, LAG, MTU or DHCP status from the running configuration
```
Solution: The firewall's running configuration did not name any interface it reports, so the integration does not use it for that firewall. The interfaces are still recorded from the firewall's interface listing. Report the firewall's model and PAN-OS version to support@netboxlabs.com.
A firewall has no addresses or VLANs:
```
Managed device PA-VM reports no usable serial ('unknown'). It gets no nbl_matching_id, no VLAN group, no routing instance and no address
```
Solution: The routing instances, VLAN group, and relayed calls of a firewall all depend on its serial number. A firewall that reports none is recorded from the inventory only. Check the firewall's serial number in Panorama.
A call to Panorama fails:
```
Fatal error running Palo Alto Panorama integration backend: Panorama answered with PAN-OS code 17: <message>
```
```
Fatal error running Palo Alto Panorama integration backend: Panorama answered HTTP 502 Bad Gateway
```
Solution: A call to Panorama itself, such as reading its inventory, device groups, or template stacks, failed, so the run stops. The first form is an error answer from Panorama, with its PAN-OS code and message. The second is an HTTP error, often from a proxy or load balancer in front of Panorama. Check that PANORAMA_HOST points at Panorama itself, and that Panorama answers its XML API.
Key generation returns no key:
```
Fatal error running Palo Alto Panorama integration backend: Panorama answered with PAN-OS code None: the key-generation answer holds no key
```
Solution: Panorama accepted the username and password but returned no API key. Check that PANORAMA_HOST points at Panorama, or set PANORAMA_API_KEY instead of the username and password.
An address is skipped:
```
Skipping the address '10.1.1.1' of pafw1 interface ethernet1/1: it is not an address with a prefix length
```
Solution: The firewall reported an address without a prefix length, or a value that is not an address, so it is not recorded. The interface is still recorded. The same warning, naming the management address, means that the firewall reported no netmask for its management address, so the device gets no primary IPv4 address.
Discovered objects do not appear in NetBox:

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.
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 and applied the resulting deviations in NetBox Assurance before running the full sync.

Frequently Asked Questions

Q: Does the integration write anything to Panorama or the firewalls?

A: No. The integration is read-only, and a read-only Panorama account is enough. It runs operational show commands on Panorama, and relays them through Panorama to the firewalls. It never changes configuration.

Q: Does the integration connect to each firewall?

A: No. It connects only to Panorama, which relays each command to the firewall. Firewalls need no credentials of their own, and the agent host needs no network access to the firewalls.

Q: Are firewalls that Panorama does not manage synced?

A: No. Only firewalls in Panorama's inventory are read.

Q: Is security policy synced?

A: No. Security rules, NAT rules, address objects, and other policy configuration are not read. Each interface's security zone is recorded in the panorama_zone custom field.

Q: Where do my firewalls land in NetBox?

A: By default, every firewall from one Panorama lands in one site named after that Panorama: PANORAMA_NAME, or Panorama's hostname. Set SITE_NAME to use one site you choose, or SITE_FROM_HOSTNAME_REGEX to take each firewall's site from its hostname. Decide before the first run, because a later change moves every firewall. See Choosing a site and a Panorama name.

Q: Why are device groups and template stacks custom fields, not tenants or tags?

A: An operator can move a firewall between device groups and template stacks. Recording them as custom fields lets them change without changing the firewall's identity in NetBox. They are in panorama_device_group, panorama_template_stack, and panorama_templates.

Q: How are high-availability pairs shown?

A: Each member records its state in panorama_ha_state, its peer's serial number in panorama_ha_peer_serial, and the pair's mode in panorama_ha_mode. No NetBox redundancy group is created. Find a firewall's peer by searching for the serial number in panorama_ha_peer_serial.

Q: Why does each firewall have its own VRFs?

A: The members of a high-availability pair hold identical interface addresses. Giving each firewall's virtual routers their own VRFs, named <hostname>:<instance>, keeps the two sets of addresses separate. See Routing Instances.

Q: Why is the management address in a VRF of its own?

A: PAN-OS routes the management port apart from every virtual router, so its address is placed in the firewall's <hostname>:management VRF. Two firewalls that report the same management address, for example behind NAT, therefore stay two records.

Q: What is the pan: route distinguisher on each VRF?

A: It is generated by the integration from the firewall's serial number and the routing instance name, so the VRF keeps its identity when the firewall is renamed. It is not a route distinguisher used in your network, and must not be copied into a routing configuration.

Q: Why is a port held down by high availability shown as enabled?

A: Enabled records whether an operator turned the port on in the configuration, not whether its link is up. The live link state is in the panorama_link_state custom field.

Q: Can I stop link state changes from producing deviations?

A: Yes. Set PANORAMA_SYNC_LINK_STATE: false. The panorama_link_state field then holds not synced. The first run after the change updates each interface once. See Link state.

Q: Why do I have old DHCP addresses in NetBox?

A: An interface that gets its address from DHCP contributes that address with the status dhcp. When the lease moves, the new address is created and the old record stays, because the integration does not delete NetBox objects. Filter IP addresses by the DHCP status to find them.

Q: What happens when two Panoramas manage the same firewall?

A: The firewall becomes one NetBox device, because it is identified by its serial number. Both policies must place it in the same site. While both report it, the fields that describe each Panorama, such as panorama_instance, change on every run.

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

A: No. The integration does not delete NetBox objects. Firewalls removed from Panorama, and interfaces and addresses removed from a firewall, remain in NetBox. Handle these removals manually.

Q: How do I sync more than one Panorama?

A: Add a policy for each Panorama, each with its own PANORAMA_HOST, credentials, and PANORAMA_NAME.

Q: Can I sync only some of my firewalls?

A: Yes. Set scope.device_groups to a list of device groups, which includes their child groups, or scope.serials to a list of serial numbers. See scope Parameters.

Common Issues

Frequently Asked Questions

On this page