Skip to main content

Networking Issues Troubleshooting

This page addresses common networking problems you may encounter with the NuNet Appliance and provides step-by-step solutions.

Common Networking Problems​

Problem: Cannot Access Appliance Dashboard​

Symptoms:

  • Cannot connect to the appliance URL
  • Browser shows "connection refused" or "site can't be reached"
  • QR code doesn't work

Solutions:

  1. Verify Appliance is Running

    • Check VirtualBox to ensure the appliance VM is running
    • Look for the QR code and URL on the appliance console

  2. Check Network Adapter Settings

    • Ensure the network adapter is set to Bridged Adapter mode
    • Verify the correct network adapter is selected
    • See Network Settings for configuration

  3. Verify Local Network Access

    • Ensure your device is on the same local network as the appliance
    • Try accessing the appliance from a different device on the same network
    • Check if firewall is blocking the connection

  4. Check macOS Local Network Permission

    • On macOS, go to System Settings → Privacy & Security → Local Network
    • Enable network access for your browser
    • See macOS Local Network Permission for details

Problem: Port 443 is Closed​

Symptoms:

  • Port checker shows port 443 as closed
  • External deployments fail
  • Cannot access deployments from outside local network

Solutions:

  1. Verify Port Forwarding Configuration

    • Check router port forwarding rules
    • Ensure external port 443 forwards to appliance's local IP on port 443
    • Verify the appliance's local IP hasn't changed
    • See Port Forwarding Setup for detailed steps

  2. Check Router Firewall

    • Ensure router firewall allows port 443
    • Check for any firewall rules blocking incoming connections
    • Temporarily disable firewall to test (re-enable after testing)

  3. Verify ISP Restrictions

    • Some ISPs block port 443 on residential connections
    • Contact your ISP to confirm port 443 is available
    • See Questions to Ask Your ISP for guidance

  4. Check for Carrier-Grade NAT

    • If behind carrier-grade NAT, port forwarding won't work
    • Request a public IP address from your ISP
    • Consider upgrading to a business connection

Problem: Deployments Fail Due to Network Issues​

Symptoms:

  • Deployments start but fail to connect
  • Containers cannot communicate with network
  • Timeout errors during deployment

Solutions:

  1. Verify Network Connectivity

    • Check appliance dashboard for network status
    • Ensure appliance has internet connectivity
    • Test network connection from appliance console

  2. Check Port Forwarding

    • Verify port 443 is open and forwarded correctly
    • Test port forwarding with port checker websites
    • See Port Checker Websites

  3. Verify Organization Membership

    • Ensure you've joined an organization
    • Check that DDNS/URL capabilities are enabled
    • See DDNS Not Working for details

  4. Check Resource Availability

    • Ensure sufficient resources are available
    • Verify host machine isn't using all resources
    • See Resource Conflicts for guidance

Problem: Cannot Connect to Peers​

Symptoms:

  • Dashboard shows no connected peers
  • Cannot establish peer-to-peer connections
  • Network connectivity issues

Solutions:

  1. Check Network Adapter Configuration

    • Verify Bridged Adapter mode is enabled
    • Ensure correct network adapter is selected
    • Restart appliance after changing network settings

  2. Verify Firewall Settings

    • Check router firewall allows peer-to-peer connections
    • Ensure necessary ports are open
    • Check host machine firewall settings

  3. Check Internet Connection

    • Verify stable internet connection
    • Test connection speed and stability
    • Ensure no network outages or restrictions

  4. Verify Organization Membership

    • Ensure you're onboarded to an organization
    • Check that network capabilities are granted
    • Restart DMS if recently joined organization

Problem: DNS/URL Not Working​

Symptoms:

  • Deployment URLs don't resolve
  • DNS names don't work
  • Cannot access deployments via URL

Solutions:

  1. Verify Organization Membership

    • DDNS/URL requires organization membership
    • Check onboarding status in dashboard
    • See DDNS Not Working for detailed troubleshooting

  2. Check DNS Configuration

    • Verify DNS name is correctly configured in ensemble
    • Ensure DNS name is unique and valid
    • Check that organization has DDNS capabilities enabled

  3. Verify Port Forwarding

    • Ensure port 443 is open and forwarded
    • Test port accessibility with port checkers
    • See Port Forwarding Setup

Problem: Slow Network Performance​

Symptoms:

  • Slow deployment times
  • Delayed container startup
  • Poor network responsiveness

Solutions:

  1. Check Internet Connection Speed

    • Test your internet connection speed
    • Ensure sufficient bandwidth for deployments
    • Consider upgrading connection if needed

  2. Monitor Resource Usage

    • Check if host machine is using network resources
    • Close unnecessary network-intensive applications
    • See Resource Conflicts

  3. Verify Network Adapter

    • Ensure using Bridged Adapter mode (not NAT)
    • Check network adapter performance
    • Consider using wired connection instead of Wi-Fi

  4. Check Router Performance

    • Ensure router can handle the traffic
    • Consider router upgrade if outdated
    • Check for router firmware updates

Diagnostic Steps​

Step 1: Verify Basic Connectivity​

  1. Check Appliance Status

    • Verify appliance is running in VirtualBox
    • Check dashboard for status indicators
    • Verify DMS is running

  2. Test Local Network Access

    • Access appliance dashboard from local network
    • Verify QR code and URL are displayed
    • Test connection from multiple devices

Step 2: Check Port Forwarding​

  1. Find Your Public IP

    • Check router status page
    • Use a service like whatismyip.com

  2. Test Port 443

  3. Verify Router Configuration

    • Check port forwarding rules
    • Verify appliance local IP is correct
    • Ensure rule is enabled

Step 3: Verify ISP and Network Setup​

  1. Check for Public IP

    • Verify you have a public IP (not behind carrier-grade NAT)
    • Contact ISP if needed

  2. Test ISP Restrictions

Step 4: Check Organization and Capabilities​

  1. Verify Organization Membership

    • Check onboarding status
    • Ensure organization membership is active
    • Verify capabilities are granted

  2. Check DMS Status

    • Restart DMS if needed
    • Verify capabilities are anchored
    • Check for error messages

Quick Reference Checklist​

Use this checklist to systematically troubleshoot networking issues:

  • Appliance is running in VirtualBox
  • Network adapter is set to Bridged Adapter mode
  • Appliance has a local IP address
  • Can access appliance dashboard locally
  • Port 443 forwarding is configured in router
  • Port 443 shows as "Open" on port checker
  • Have a public IP address (not carrier-grade NAT)
  • ISP allows port forwarding
  • Router firewall allows port 443
  • Joined an organization (for DDNS/URL)
  • DMS is running and healthy
  • Sufficient resources available on host machine

Getting Additional Help​

If you've tried all troubleshooting steps and issues persist:

  1. Review Comprehensive Networking Guide

  2. Check Related Troubleshooting Pages

  3. Contact Support

    • Use the Support Process
    • Include network configuration details
    • Provide port checker results
    • Share router and ISP information