Skip to main content

Troubleshooting & FAQ

This page lists common synthetic-device problems by symptom, with the fix for each. For the field choices behind most of them, see Configuring Connections; for NQE-based connections, see Automated Setup with NQE.

I'm not sure which device type to use​

See Choosing a Device. The quick cut: public internet → Internet node; private inter-site L3 → Intranet node; an external partner network you send to but don't route through → Adjacent network; provider MPLS with route inference from CE BGP → L3 VPN; one L2 broadcast domain over the WAN → L2 VPN; a single point-to-point L2 link → WAN Circuit; IPSEC tunnel → Encryptor.

My changes didn't take effect​

Synthetic-device changes apply to the next processed snapshot, not the current one. Saving stores the configuration but leaves existing snapshots unchanged. To see the change, reprocess the current snapshot or collect a new one.

Dynamic (NQE) connections are empty or look wrong​

A dynamic-connection query that fails at run time leaves the synthetic device with no connections and doesn't flag itself in the topology. To diagnose:

  1. Inspect the device's stored configuration (in the UI, or GET it via the API). A failed query leaves a queryResult holding an error — for example a QUERY_RUN_ERROR whose message names a type mismatch.
  2. Re-run the query in the NQE editor against the same snapshot and confirm it returns rows of the expected type.
  3. Check the common NQE mistakes: backdoorInterfaces (plural), subnetDiscoveryMethod (not subnetAutoDiscovery), VLAN null rather than 0, restricted site-name characters, peerIps as a List<IpAddress>, and correct field value types.

The discovered subnets are wrong​

  • Set to From BGP routes but the subnets look like the full routing table. If eBGP advertisements weren't collected on the gateway, the connection falls back to the From IP routes mode. Confirm BGP advertisement collection is enabled for the gateway device — see BGP advertisement collection.
  • A prefix appears that reaches its destination another way. The gateway forwards it out a side link (a tunnel or a direct site-to-site link), so the From IP routes mode counts it as advertised across the segment. Mark that link as a backdoor port so its subnets are subtracted.
  • Private addresses missing from an Internet node. Expected — the internet node routes only public addresses. Use an Intranet node for private space.

A path sources from the Internet node when it shouldn't​

The source address is public and isn't located at any collected site, so it falls to the internet node. Forward moves a public prefix off the internet node only when the prefix reaches the node through one of its connections: as a BGP advertisement, a learned or advertised subnet, a gateway interface address, or an entry in the connection's subnets list. Public space you route internally but never advertise to an internet-node connection stays invisible to that logic, so it keeps landing on the internet node.

This is a consequence of where the internet node sits in localization: Forward matches an address against the internet-node tier before it falls back to route-table entries. See Path Analysis → Anchor resolution for the full tier order.

Add such a prefix to the internet node's exclude subnets list. Exclusion removes it from internet-node ownership, so the address drops past the internet-node tier and Forward locates it by its internal route instead. Each entry must be a valid, public CIDR block (host bits zeroed); an entry that isn't a well-formed block, or that falls in private or reserved space, is rejected on input rather than applied.

"Receives traffic from the internet" shows No for a device with a public interface​

Forward computes this from reachability, not from configuration. It runs traffic sourced at the internet node through the model and checks whether any valid path terminates on the device — that is, ends on one of the device's own interface IPs (a self or loopback address). Traffic that merely transits the device doesn't count, because a transit hop isn't where the path ends and a forwarding egress port isn't a self or loopback address. A public-facing router that only forwards internet traffic onward, without terminating any of it on its own interfaces, produces no such path and correctly shows No.

A Missing Peer appeared​

Forward creates a Missing Peer when a collected port that's an uplink to a synthetic device carries a VLAN or subinterface the synthetic device isn't configured to accept. It marks unmodeled traffic rather than dropping it silently. Either add the missing VLAN/subinterface as a connection, model it with a separate synthetic device, or leave it if that traffic is out of scope. You can't delete a Missing Peer directly — adjust the synthetic-device configuration and it goes away.

No path appears between two sites connected by a synthetic device​

A synthetic device doesn't link one site to another directly. Each connection produces a single link at that side's uplink interface to the synthetic node, so a site-to-site path is really two links in series — this site's uplink to the node, and the node to the far site's uplink. A path can break at two levels: the links, or the routing across them.

The links don't form. If a connection's uplink or gateway interface can't be resolved, that link never forms and the end-to-end path breaks. Check each side separately and confirm its connection resolves. Set the uplink and gateway per the rules in Uplink Interface vs. Gateway Interface: when the uplink is an access or trunk port and the gateway is on the same device, leave the gateway blank so Forward can infer the SVI; when the gateway is on a different device, name the exact gateway interface and VLAN, which Forward validates but doesn't infer.

The links are up but no route crosses them. Both links can form and still leave no path, if the synthetic node doesn't carry a route from the far gateway back to this site's subnet (or the reverse). The node's routing is built from each connection's subnets, whether auto-discovered from the gateway or entered by hand: a subnet is reachable across the segment only if some connection advertises it into the node. If this site's subnet was never advertised — the wrong subnet-discovery mode for how the gateway learns it, BGP advertisements not collected, a missing entry in a manually configured Subnets list, or the prefix subtracted by a backdoor port — the far side has no route to it across the node even though both links are present.

The connection editor shows only the config you entered (the discovery mode and any manual subnets), not the subnets discovery actually resolved. To see what the node ended up advertising, open the synthetic node and read its routing table:

  1. Open the synthetic node from the device inventory or a search card, like any other device.
  2. Expand Device state and open the ip_routes file. This is the node's routing table, rendered as a table. Look for this site's subnet: if it isn't there, no connection advertised it, so the far side has no route to it across the node. (A node with no routes at all has no ip_routes file.)

Repeat for the reverse direction — a synthetic-device path needs a route each way, and one side can advertise while the other doesn't. To check where a specific flow breaks, run a path search from the far site toward the subnet and read the route decision at the synthetic-node hop.

Traffic won't route through my adjacent network​

Expected. An adjacent network is a traffic sink: it accepts traffic addressed to it and can originate traffic, but it never forwards from one connection to another, so no path transits it to reach a third site. If you need the segment to carry traffic between your sites, it's a transit network — model it as an Intranet node or L3 VPN instead. If instead a path that should terminate at the partner isn't resolving, confirm the destination subnet is either listed in the adjacent network's Owned subnets or advertised by one of its connections.

An interface on the synthetic device is down​

A down interface on the synthetic device means Forward couldn't resolve that connection's parameters to a valid uplink port (and gateway port, for L3 synthetic devices). On an L3 synthetic device, each connection produces one interface: a physical L3 interface when the traffic leaving the uplink is untagged, or a subinterface when it's VLAN-tagged. Subinterfaces on the same uplink share one physical L2 parent, so a single physical link can carry several connections on different VLANs.

A connection fails to resolve when:

  • The gateway or uplink device isn't in the snapshot.
  • The gateway port doesn't exist on the gateway device, or the uplink port doesn't exist on the uplink device.
  • An L3 connection is underspecified: VLAN and gateway port are optional, but if you omit both and the uplink is an L2 interface, Forward has to guess the gateway on that device and can't always find or uniquely identify one — an access port with no subinterface or SVI for the access VLAN, or a trunk carrying several VLANs where more than one subinterface or SVI could match. Naming the VLAN or gateway port resolves it.

Fix the connection per Uplink Interface vs. Gateway Interface. Because an unresolved connection carries no routes, this is also a cause of no path between two sites.

Yes. The uplink (the port that connects to the synthetic node) and the L3 gateway that routes for it don't have to be on the same collected device. Forward only checks that both interfaces exist; it performs no VLAN normalization or SVI inference across devices, so set the VLAN and the exact gateway interface yourself — nothing is filled in for you. That inference happens only when the uplink and gateway are on the same device. See Uplink Interface vs. Gateway Interface for how the two cases differ.

The API rejects my VLAN, site name, or connection port​

  • VLAN: use null for untagged; valid tagged values are 1–4095. 0 is rejected.
  • Site name: only letters, digits, ., -, and _. Spaces, commas, and & are rejected.
  • Connection port: a self or self-zone interface can't be an uplink or gateway port, on any synthetic-device type. Pick the physical or routed interface that faces the segment instead.