--- cuppy_hub: aws cuppy_path: reference/vpc/errors.md cuppy_section: docs cuppy_doc: ZHYS-M7RY cuppy_doc_uuid: 78694e92-960e-4130-88a3-ca22d89fc39d cuppy_permalink: https://cuppy.io/aws/d/ZHYS-M7RY cuppy_version: 4 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/aws/docs/reference/vpc/errors cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: 1cd3b072788eaa7a6fd317ea63ac3e6b962351b3e23d141a81445025a447a5d2 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # VPC errors and Reachability Analyzer explanation codes **Most VPC misconfigurations never raise an error. They time out.** Run Reachability Analyzer (`guides/vpc/diagnose-connection-timeout.md`) to get an `ExplanationCode`, then look it up here. NAT gateway and quota errors, which do have text, come at the end. **Check for every code in the next five sections:** `aws ec2 describe-network-insights-analyses --network-insights-analysis-ids --query 'NetworkInsightsAnalyses[0].[NetworkPathFound,Explanations[].[ExplanationCode,Component.Id,Direction]]'`. The `Component` names the security group, ACL, route table or gateway to open; re-run the analysis after the fix, and `NetworkPathFound: true` confirms it. ## Firewalls | Code | Meaning → fix | |---|---| | `ENI_SG_RULES_MISMATCH` | No rule in the security group(s) matches the traffic. The explanation's `Direction`, `PacketField` and `Port` say which one. Add the inbound rule on the destination group, or the outbound rule on the source group | | `SG_HAS_NO_RULES` | The group has no rules in that direction at all | | `SUBNET_ACL_RESTRICTION` | The subnet's network ACL denies it. Check both directions, including the ephemeral return ports 1024–65535 | | `SG_REFERENCES_NOT_PRESERVED` | A component on the path (for example a middlebox) discards security group identity, so rules that reference a group can't match. Use CIDRs | | `SG_REFERENCING_SUPPORT` | The transit gateway VPC attachment does not have security group referencing turned on | | `UNKNOWN_PEERED_SGS` | The peer VPC is in another account, so group references across the peering are treated as denies. Enable cross-account analysis or use CIDRs | | `FIREWALL_RULES_RESTRICTION` | Blocked by an AWS Network Firewall rule | ## Routes | Code | Meaning → fix | |---|---| | `NO_ROUTE_TO_DESTINATION` | The source subnet's route table has no route that covers the destination. Add one: NAT, IGW, endpoint, peering or TGW | | `MORE_SPECIFIC_ROUTE` | A more specific route takes the traffic elsewhere | | `HIGHER_PRIORITY_ROUTE` | Another route with the same CIDR wins | | `CANNOT_ROUTE` | The route's CIDR or prefix list does not match the packet's destination | | `BAD_STATE_ROUTE` | The route is not functional, for example its target was deleted | | `VPC_LOCAL_ROUTE_CIDR_RESTRICTION` | The local route only covers the VPC CIDR | | `INGRESS_RTB_TRAFFIC_REDIRECTION` | An ingress route table sends the subnet's traffic to an appliance, so the direct IGW route isn't used | ## Gateways and endpoints | Code | Meaning → fix | |---|---| | `IGW_PUBLIC_IP_ASSOCIATION_FOR_EGRESS` | The source has no public IP, so the IGW won't carry its traffic to the internet. Assign one, or route through NAT | | `IGW_PRIVATE_IP_ASSOCIATION_FOR_INGRESS` | Inbound traffic addressed to something other than an interface's public IP | | `IGW_DESTINATION_ADDRESS_NOT_IN_RFC1918_EGRESS` | Traffic to a private address range sent to the IGW is dropped | | `NGW_REQUIRES_SOURCE_IN_VPC` | A NAT gateway won't translate traffic arriving from peering, VPN or Direct Connect | | `REGIONAL_NGW_ROUTE_AZ_RESTRICTION` | The regional NAT gateway hasn't expanded into the source's AZ yet (it can take up to 60 min) | | `VPC_BLOCK_PUBLIC_ACCESS_ENABLED` | VPC Block Public Access is blocking internet traffic. Add an exclusion or change the mode | | `VPCE_GATEWAY_PROTOCOL_RESTRICTION` | Gateway endpoints carry only TCP and ICMP echo | | `VPCE_INTRA_VPC_TRAFFIC` | An endpoint can't start connections. Analyze in the reverse direction | | `VPCE_SERVICE_NOT_INSTALLED_IN_AZ` | The endpoint service isn't in that AZ | | `PCX_REQUIRES_ADDRESS_IN_VPC_CIDR` | Peering carries traffic only between the two VPCs' CIDRs. No transit through a third network | ## Load balancers | Code | Meaning → fix | |---|---| | `ELBV2_LISTENERS_MISMATCH` / `ELBV2_LISTENER_PORT_RESTRICTION` | No listener on that port | | `ELBV2_LISTENER_HAS_NO_TG` / `ELBV2_LISTENER_REQUIRES_TG_ACCEPT` | The listener's target group is empty, or no target group accepts the traffic | | `ELBV2_NO_TARGETS_IN_AZ` / `ELB_INSTALLED_AZ_RESTRICTION` | No targets in an enabled AZ, or targets are in an AZ the load balancer doesn't have enabled | | `ELB_NOT_CROSSZONE` | Cross-zone load balancing is off | | `TARGET_PORT_RESTRICTION` | The load balancer only sends to the registered port | ## The path itself | Code | Meaning → fix | |---|---| | `DISCONNECTED_VPCS` | The VPCs are not connected (no peering, TGW…) | | `NO_PATH` | No path found. Also returned for filters that match nothing, components still starting, endpoints as sources, and **unsupported features such as IPv6**. Fall back to the manual checks | | `NO_SOURCE_OR_DESTINATION` / `UNASSOCIATED_COMPONENT` | The resource is gone, or has no IPv4 interface in a VPC of yours | | `NO_POSSIBLE_DESTINATION` | The destination is in another account or Region. Enable cross-account analysis | | `FILTER_AT_SOURCE_*` / `FILTER_AT_DESTINATION_*` | Your filter (port, address, protocol) ruled the path out. Check the filter first | ## NAT gateway errors Shown as the NAT gateway's **State message** when it goes to `Failed`, or returned by the API: | Message | Fix | Check | |---|---|---| | `Subnet has insufficient free addresses to create this NAT gateway` | Free IPs in the subnet, or use another subnet | `aws ec2 describe-subnets --subnet-ids --query 'Subnets[0].AvailableIpAddressCount'` | | `Network vpc-… has no internet gateway attached` | Attach an internet gateway first. Even private-subnet NAT needs one in the VPC | `aws ec2 describe-internet-gateways --filters Name=attachment.vpc-id,Values=` | | `Elastic IP address eipalloc-… is already associated` | Disassociate it from the other resource, or allocate a new one | `aws ec2 describe-addresses --allocation-ids ` → `AssociationId` | | `Performing this operation would exceed the limit of NAT gateways` | The NAT-gateways-per-AZ quota. Pending, available and deleting gateways all count. Wait for deletes, use another AZ, or request an increase | `aws ec2 describe-nat-gateways --filter Name=subnet-id,Values=` (count pending, available, deleting) | | `The maximum number of addresses has been reached.` | The Elastic IP quota for the Region | `aws ec2 describe-addresses --query 'length(Addresses)'`; Service Quotas for EC2-VPC Elastic IPs | | `NotAvailableInZone` | A constrained AZ that NAT gateways don't support. Put the NAT gateway in another AZ | Creating in another AZ's subnet succeeds | A `Failed` NAT gateway stays visible for about an hour, then it is deleted automatically. ## Security group rule state A rule referencing a group in a peer or shared VPC is marked **stale** when that group or the peering connection is deleted. It allows nothing until you remove or replace it. ## When none of these fits Run Reachability Analyzer between the exact source and destination (`aws ec2 create-network-insights-path`, then `start-network-insights-analysis`). It names the blocking component. Then confirm with flow logs on both ENIs (`reference/vpc/flow-logs.md`, queries in `reference/cloudwatch/logs-insights-queries.md`). If both show ACCEPT and it still fails, the problem is above the network: TLS, DNS, or the application. --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 131 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/aws/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.