CNI Gotchas & Troubleshooting

Common Errors

"Status: Pending"

Cause: Cross-connect not installed, RX/TX fibers reversed, wrong fiber type, or low light levels Solution:

1. Verify cross-connect installed
2. Check fiber at patch panel
3. Swap RX/TX fibers
4. Check light with optical power meter (target > -20 dBm)
5. Contact account team

"Status: Unhealthy"

Cause: Physical issue, low light (<-20 dBm), optic mismatch, or dirty connectors Solution:

1. Check physical connections
2. Clean fiber connectors
3. Verify optic types (10GBASE-LR/100GBASE-LR4)
4. Test with known-good optics
5. Check patch panel
6. Contact account team

"BGP Session Down"

Cause: Wrong IP addressing, wrong ASN, password mismatch, or firewall blocking TCP/179 Solution:

1. Verify IPs match CNI object
2. Confirm ASN correct
3. Check BGP password
4. Verify no firewall on TCP/179
5. Check BGP logs
6. Review BGP timers

"Low Throughput"

Cause: MTU mismatch, fragmentation, single GRE tunnel (v1), or routing inefficiency Solution:

1. Check MTU (1500↓/1476↑ for v1, 1500 both for v2)
2. Test various packet sizes
3. Add more GRE tunnels (v1)
4. Consider upgrading to v2
5. Review routing tables
6. Use LACP for bundling (v1)

API Errors

400 Bad Request: "slot_id already occupied"

Cause: Another interconnect already uses this slot
Solution: Use occupied=false filter when listing slots:

await client.networkInterconnects.slots.list({
  account_id: id,
  occupied: false,
  facility: 'EWR1',
});

400 Bad Request: "invalid facility code"

Cause: Typo or unsupported facility
Solution: Check locations PDF for valid codes

403 Forbidden: "Enterprise plan required"

Cause: Account not enterprise-level
Solution: Contact account team to upgrade

422 Unprocessable: "validate_only request failed"

Cause: Dry-run validation found issues (wrong slot, invalid config)
Solution: Review error message details, fix config before real creation

Rate Limiting

Limit: 1200 requests/5min per token
Solution: Implement exponential backoff, cache slot listings

Cloud-Specific Issues

AWS Direct Connect: "VLAN not matching"

Cause: VLAN ID from AWS LOA doesn't match CNI config
Solution:

1. Get VLAN from AWS Console after ordering
2. Send exact VLAN to CF account team
3. Verify match in CNI object config

AWS: "Connection stuck in Pending"

Cause: LOA not provided to CF or AWS connection not accepted
Solution:

1. Verify AWS connection status is "Available"
2. Confirm LOA sent to CF account team
3. Wait for CF team acceptance (can take days)

GCP: "BGP routes not propagating"

Cause: BGP routes from GCP Cloud Router ignored by design
Solution: Use static routes in Magic WAN instead

GCP: "Cannot query VLAN attachment status via API"

Cause: GCP Cloud Interconnect Dashboard-only (no API yet)
Solution: Check status in CF Dashboard or GCP Console

Partner Interconnect Issues

Equinix: "Virtual circuit not appearing"

Cause: CF hasn't accepted Equinix connection request
Solution:

1. Verify VC created in Equinix Fabric Portal
2. Contact CF account team to accept
3. Allow 2-3 business days

Console Connect/Megaport: "API creation fails"

Cause: Partner interconnects require partner portal + CF approval
Solution: Cannot fully automate. Order in partner portal, notify CF account team.

Anti-Patterns

What's Not Queryable via API

Cannot retrieve:

• BGP session state (use Dashboard or BGP logs)
• Light levels (contact account team)
• Historical metrics (uptime, traffic)
• Bandwidth utilization per interconnect
• Maintenance window schedules (notifications only)
• Fiber path details
• Cross-connect installation status

Workarounds:

• External monitoring for BGP state
• Log aggregation for historical data
• Notifications for maintenance windows

Limits