Troubleshooting Guide

This guide helps you solve common problems with UnboundBytes. Start by finding the issue that matches yours.

Device Issues

Device Won’t Connect

Symptoms:

• Device status shows “Offline” in the portal
• Agent won’t start or crashes on launch
• Portal says device hasn’t checked in

Solutions:

1. Check your internet connection

   • Verify you have stable internet
   • Check if other devices can connect to the network
   • Try pinging a public server (e.g., ping 8.8.8.8)

2. Restart the agent

   • Stop the agent process (Ctrl+C or close the window)
   • Wait 10 seconds
   • Start the agent again
   • Check if it connects within 30 seconds

3. Check firewall rules

   • Verify the agent isn’t blocked by a firewall
   • Check Windows Defender Firewall (Windows) or iptables (Linux)
   • If necessary, add the agent to firewall exceptions

4. Review agent logs

   • Agent logs should show connection attempts
   • Look for network-related errors
   • If you see “Connection refused”, your device can’t reach our servers

5. Verify device credentials

   • The pairing code expires after 15 minutes
   • If pairing failed, generate a new pairing code
   • Try pairing again with the fresh code

Device Is Slow to Respond

Symptoms:

• Health checks take a long time
• Portal feels sluggish
• Device shows “Degraded” status

Solutions:

1. Check system resources

   # Linux/Mac: Check CPU and memory usage
   top
   
   # Windows: Open Task Manager (Ctrl+Shift+Esc)

2. Look for high disk usage

   • Check if disk is >85% full
   • Delete old backups if storage is full
   • Clear logs if needed

3. Check network latency

   • Test your internet connection speed
   • Check for network congestion at your location
   • Restart your router if internet is slow

4. Restart the device

   • Reboot your server/machine
   • Wait 2-3 minutes for services to start
   • Check if responsiveness improves

Device Keeps Disconnecting

Symptoms:

• Device connects then disconnects repeatedly
• Portal shows alternating online/offline status
• Agent crashes frequently

Solutions:

1. Check for DNS issues

   # Verify DNS is working
   nslookup api.unboundbytes.com

2. Look for power issues

   • Ensure device isn’t sleep/hibernating
   • Check if power saving is disabled
   • Verify stable power supply

3. Review agent logs for patterns

   • Note the time when disconnections happen
   • Look for repeated error messages
   • Check if it’s related to specific times

4. Update agent to latest version

   • Download the newest agent version
   • Stop the old agent
   • Install and run the new version

5. Contact support

   • Provide agent logs with timestamps
   • Include your device OS and connection type
   • Save the output of api.unboundbytes.com DNS lookups

Application Deployment Issues

Deployment Stuck in “Pending”

Symptoms:

• Deployment shows “Pending” but never starts
• Progress bar doesn’t move
• This has been happening for >10 minutes

Solutions:

1. Check device connectivity

   • Make sure device is online (green status in portal)
   • Verify device has accepted the deployment command
   • Check device has free disk space

2. Verify Docker is running

   # Linux/Mac
   docker ps
   
   # Windows (Docker Desktop)
   # Ensure Docker Desktop is running in system tray

3. Check system resources

   • Ensure device has at least 4GB free RAM
   • Verify device has >20GB free disk space
   • Check CPU isn’t constantly at 100%

4. Cancel and retry

   • Click “Cancel Deployment” in the portal
   • Wait 30 seconds
   • Try deploying again

Deployment Fails During “Deploying”

Symptoms:

• Deployment starts but then fails
• Shows an error message about Docker or configuration
• Application status shows “Error”

Solutions:

1. Check the error message

   • Read the full error in the deployment logs
   • Common errors: port already in use, insufficient resources, missing environment

2. For “Port already in use” errors

   • Stop other applications using that port
   • Or configure the app to use a different port
   • Redeploy the application

3. For “Out of memory” errors

   • Close other applications on the device
   • Restart the device to free memory
   • Consider upgrading device resources
   • Reduce the app’s memory allocation if possible

4. For “Docker not running” errors

   • Start Docker (Docker Desktop on Windows/Mac, service on Linux)
   • Restart the agent
   • Retry deployment

5. Check application-specific issues

   • Verify all required environment variables are set
   • Check if the app image is available
   • Review Docker Compose configuration

6. Contact support

   • Provide the full error message
   • Include device logs from the deployment time
   • Save the Docker Compose file if possible

Can’t Access Application

Symptoms:

• Application shows “Running” but you can’t access it
• Browser shows “Connection refused” or timeout
• Invalid address or can’t reach that website

Solutions:

1. Check application is actually running

   • Verify status shows “Running” in portal
   • Not “Stopped”, “Error”, or “Deploying”

2. Verify the access URL

   • Check the correct URL in application settings
   • Try accessing from a different browser
   • Try accessing from a different device

3. Check firewall settings

   • Verify ports aren’t blocked by firewall
   • On Windows: Check Windows Defender Firewall
   • On Linux: Check iptables or firewall rules
   • On Mac: Check System Preferences → Security & Privacy

4. Check network connectivity

   • Can your device reach the internet?
   • Can your computer reach your device?
   • Try accessing from another device on the network

5. Verify DNS configuration (for custom domains)

   • Check CNAME record points to correct tunnel URL
   • Wait for DNS propagation (can take 15-30 minutes)
   • Use nslookup to verify DNS resolution

6. Restart the application

   • Click “Restart” in the portal
   • Wait for application to fully start
   • Try accessing again

Application Performance Issues

Application Responses Are Slow

Symptoms:

• Pages load slowly
• Operations timeout
• Responses take >3 seconds

Solutions:

1. Check device resources

   • Monitor CPU and memory usage
   • Look for high disk I/O
   • Verify network latency to device

2. Check application logs

   • Click “View Logs” in the application menu
   • Look for errors or slow queries
   • Search for database timeouts

3. Reduce load on the device

   • Stop unnecessary applications
   • Limit number of concurrent users
   • Close heavy processes

4. Optimize application settings

   • Check app configuration for performance options
   • Disable heavy features you don’t use
   • Adjust cache settings if available

5. Upgrade device resources

   • More CPU helps with processing
   • More RAM helps with concurrency
   • SSD storage helps with disk I/O

Application Uses Excessive Memory

Symptoms:

• Memory usage constantly above 85%
• Application becomes unresponsive
• System starts swapping to disk

Solutions:

1. Identify the memory leak

   • Check if memory grows over time
   • Restart the application and monitor
   • Note when memory starts increasing

2. Restart the application

   • Stop the app cleanly
   • Wait 10 seconds
   • Start it again
   • Monitor memory for improvement

3. Reduce application load

   • Limit number of users/connections
   • Disable heavy features
   • Clean up old data in the app

4. Upgrade device resources

   • Add more RAM to the device
   • Run fewer applications
   • Move to a more powerful device

5. Report the issue

   • Note when it started
   • Include application type and version
   • Provide memory usage graphs if available

Application Uses Excessive CPU

Symptoms:

• CPU usage constantly above 80%
• Application is slow even when memory is available
• Device becomes unresponsive

Solutions:

1. Check what’s using CPU

   • Identify if it’s the app or something else
   • Check for background tasks or backups
   • Look for runaway processes

2. Pause heavy operations

   • Stop indexing or background jobs if possible
   • Reduce number of concurrent operations
   • Wait for long operations to complete

3. Optimize application settings

   • Reduce worker threads if configurable
   • Lower quality/resolution settings
   • Disable heavy features you don’t need

4. Restart the application

   • May reset internal state causing high CPU
   • Monitor CPU after restart
   • See if issue returns

5. Upgrade device resources

   • More CPU cores help with parallel tasks
   • Consider a more powerful device
   • Run fewer applications simultaneously

Backup & Recovery Issues

Backup Fails to Complete

Symptoms:

• Backup creation times out
• Backup shows “Failed” status
• Backup didn’t complete after >30 minutes

Solutions:

1. Check available disk space

   • Backups need free space to work
   • Ensure >10% free disk space
   • Delete old backups if needed

2. Verify network connectivity

   • Device must have steady internet
   • Backup upload can take time for large apps
   • Check if network is stable

3. Reduce backup size

   • Create backup of configuration only
   • Exclude large data volumes if possible
   • Split large applications into multiple instances

4. Try backup again

   • Wait 5 minutes after failure
   • Check if device is responsive
   • Create new backup attempt

5. Check device logs

   • Look for disk I/O errors
   • Check for out-of-memory errors
   • Review network errors

Backup Verification Failed

Symptoms:

• Backup shows “Verification Failed”
• Can’t restore from this backup
• Trust icon shows a warning

Solutions:

1. Don’t use this backup

   • Create a new backup instead
   • Verified status means the old one is unreliable
   • Only restore from “Verified” backups

2. Check device network

   • Verification needs to upload/download from cloud storage
   • Ensure stable internet connection
   • Retry backup verification

3. Create new backup

   • Most recent backups are usually fine
   • Only old backups occasionally fail verification
   • Create fresh backup to ensure you have good copy

4. Contact support

   • If multiple backups fail verification
   • Include timestamps of failed backups
   • Provide device connectivity details

Restore Fails

Symptoms:

• Restore appears to start but then fails
• Application won’t start after restore
• Error message about corrupted backup

Solutions:

1. Verify backup is healthy

   • Check that backup shows “Verified” status
   • Don’t restore from failed backups
   • Try with a different backup first

2. Ensure device is healthy

   • Device must be online
   • Device must have >20GB free disk space
   • Device Docker must be functional

3. Try restore again

   • Wait 1 minute after initial failure
   • Re-select the backup
   • Click “Restore” again

4. Check if manual recovery is needed

   • If restore still fails, contact support
   • Have backup ID and error message ready
   • May need to restore configuration only

Custom Domain Issues

Custom Domain Not Working

Symptoms:

• Custom domain URL shows “Connection refused”
• Domain “Pending Verification” for >30 minutes
• SSL certificate error

Solutions:

1. Verify DNS configuration

   nslookup yourdomain.com

   • Should show CNAME pointing to tunnel
   • May take 15-30 minutes to propagate
   • Different DNS providers have different caches

2. Wait for DNS propagation

   • Global DNS takes 24-48 hours to fully propagate
   • Try accessing from different locations
   • Use online DNS checker tools

3. Check CNAME record

   • Verify it matches the tunnel URL exactly
   • Ensure no extra spaces or characters
   • Check you’re updating the correct domain

4. Verify domain ownership

   • Ensure you have access to domain’s DNS settings
   • Verify CNAME record is actually saved
   • Try manually refreshing verification

5. Check SSL certificate

   • Certificate issuance can take a few minutes
   • Allow up to 10 minutes for HTTPS to work
   • Try HTTP first, then HTTPS after waiting

6. Contact support

   • If domain still doesn’t work after 1 hour
   • Provide domain name and tunnel URL
   • Include DNS records showing CNAME

Getting Help

Before Contacting Support

Gather this information:

1. Device information

   • Operating System (Windows/Mac/Linux)
   • Device name in portal
   • Current online status

2. Application information

   • Application name and type
   • Current status in portal
   • Last time it worked

3. Error details

   • Full error message text
   • When error occurs (always, sometimes, after action)
   • Steps to reproduce

4. Relevant logs

   • Device agent logs
   • Application logs
   • Browser console errors (for web issues)

How to Get Help

• Documentation: Search this guide for your issue
• Portal Support: Submit ticket through settings
• Community Chat: Ask in community forums
• Email Support: Email support@unboundbytes.com

Providing Logs

When contacting support with logs:

1. Save logs to a text file
2. Include only relevant time period (±5 minutes around error)
3. Remove any personal information
4. Describe what was happening when error occurred

See Also

• Health Monitoring - Monitor your applications
• Backups & Recovery - Backup and restore your data
• Quick Start Guide - Deploy your first app