Troubleshooting

If you encounter difficulties while establishing or operating your STACKIT VPN, use this guide to identify and resolve common errors. Most issues relate to configuration mismatches between the STACKIT gateway and your remote peer. The service provides specific status indicators and logs to help you determine whether the problem lies with the gateway infrastructure, the connection logic, the IPSec tunnels, or the BGP peering.

Troubleshooting the VPN gateway

Gateway issues usually relate to the underlying virtual infrastructure or project-level constraints. Monitor the gateway state by retrieving its details via the API or the STACKIT Portal.

Provisioning of all necessary VPN Gateway resources may take some time. If the VPN Gateway is not moving to the READY state within 45 minutes after creating it please contact the STACKIT Support team.

Troubleshooting VPN connections

A connection acts as the logical grouping of two parallel tunnels. If a connection fails to reach the READY state, it often indicates a configuration error in the request parameters.

Ensure the routingType (for example, POLICY_BASED or ROUTE_BASED) matches the capabilities of your remote peer. You cannot change this after the gateway is created.

Troubleshooting VPN tunnels

Because STACKIT VPN uses an active-active architecture, you must monitor both tunnel1 and tunnel2. Issues here are typically related to the IPSec handshake and authentication.

Remote IP mismatch (connection failures)

Ensure the remoteAddress of tunnel1 and tunnel2connection settings matches your public IP address of your local site. The VPN Gateway only allows connections from these configured addresses. Connection attempts from any other public IPs are rejected. Ensure that the your onsite gateway points to the correct public IPs of your STACKIT VPN Gateway.

IKEv1 vs. IKEv2 (protocol mismatch)

Ensure your remote peer is not attempting to negotiate using IKEv1. Handshakes using IKEv1 will fail silently with no proposal being selected.

Encryption suites

Verify that your peer’s proposal for encryption (for example, AES-256), hashing (for example, SHA-256), and Diffie-Hellman groups matches the supported and configured STACKIT parameters.

Authentication failures

Pre-shared key (PSK) mismatch

The preSharedKey is case-sensitive and must be at least 20 characters long. Ensure the key on your remote peer matches the one provided to STACKIT exactly.

Identifier (ID) mismatch

Verify that your remote peer is using the correct IKE IDs. The remote peer should identify the STACKIT gateway by its assigned public IPv4 address.

Enable asymmetric routing

Because STACKIT VPN utilizes an active-active architecture, traffic can enter through tunnel1 and return through tunnel2 if both are used.

Ensure your remote peer device is configured to handle asymmetric traffic. If your device performs strict “Reverse Path Forwarding” (RPF) checks, it may drop legitimate return traffic.

Traffic selector issues

Subnet mismatches

In POLICY_BASED configurations, the localSubnets and remoteSubnets must be exact mirrors of the configuration on your peer device.

Encapsulation overhead

If small packets pass but large packets fail, configure MSS clamping on your remote peer (typically to 1350–1380 bytes). This prevents packets from being dropped due to MTU limits.

Troubleshooting BGP dynamic routing

If your tunnels are READY but routes are not being exchanged, verify your BGP configuration.

Autonomous System Number (ASN) validation

Ensure you are using a private ASN. Valid 16-bit ASNs fall within the range 64512 to 65534. Valid 32-bit ASNs fall within the range 4200000000 to 4294967294.

Peering address connectivity

Verify that the localAddress and remoteAddress in the peering configuration are in the same subnet. These internal IPs serve as the next-hop identifiers for the BGP session.

Firewall rules

Ensure your remote firewall allows BGP traffic on TCP port 179.

BGP multi-path

If using BGP_ROUTE_BASED routing, ensure your peer device supports “Equal-Cost Multi-Path” (ECMP) to balance traffic across both tunnels effectively.

Verify security group rules

Even if your VPN connection is READY, your STACKIT Security Groups / ACLs might block the application traffic.

Contact support

If you cannot resolve the issue after following these steps, please provide the following information to the STACKIT support team:

• Your STACKIT project ID.
• The gatewayId and connectionId.
• Logs from your remote peer device showing the IKE/IPSec handshake attempts.
• The approximate timestamp when the issue first occurred