Beam

Troubleshooting

This guide helps you diagnose and resolve common issues with Beam. Start with the quick diagnosis section to identify your problem, then follow the relevant solution.

Quick Diagnosis

Before diving into specific issues, run these commands to gather diagnostic information:

Diagnostic commands
1
2
3
4
5
6
7
8
# Check Beam version
beam --version
# View tunnel status
beam --verbose
# Test local connectivity
curl -v http://localhost:3000

If the tunnel starts but requests fail, the issue is likely network-related. If the tunnel fails to start, check the error message — it usually indicates the specific problem.

Tunnel Won't Start

The most common startup issue is that your local application isn't running or the port is already in use.

Port Already in Use

If you see "address already in use" or "EADDRINUSE", another process is using that port.

Terminal
1
2
3
4
5
6
7
8
# Find what's using port 3000
lsof -i :3000
# Kill the process (macOS/Linux)
lsof -ti:3000 | xargs kill -9
# Or use a different port
beam 3001

Application Not Running

Beam needs something to forward traffic to. Make sure your application is running first.

Terminal
1
2
3
4
5
6
7
8
# Verify your application is accessible
curl http://localhost:3000
# If curl fails, start your application first
npm run dev  # or your start command
# Then start the tunnel
beam 3000

Permission Denied

On some systems, binding to certain ports or creating network connections requires elevated privileges. This is especially common when using the DNS server feature.

Terminal
1
2
3
4
5
6
# Run with sudo if needed for DNS features
sudo beam 3000 --domain myapp.local
# Or configure your system to allow non-root port binding
# macOS: no action needed for ports > 1024
# Linux: sudo setcap 'cap_net_bind_service=+ep' $(which node)

Tor Connection Issues

Beam uses Tor to create hidden services. Connection issues typically fall into a few categories.

Tor Bootstrap Taking Too Long

The first time you run Beam, Tor needs to build circuits. This normally takes 10-30 seconds, but can take longer on slow networks or if Tor relay availability is limited.

Terminal
1
2
3
4
5
6
7
8
# Run with verbose output to see progress
beam 3000 --verbose
# You'll see messages like:
# [Tor] Bootstrapping: 0%
# [Tor] Bootstrapping: 25%
# [Tor] Bootstrapping: 50%
# [Tor] Circuit established

If bootstrap stalls below 50%, your network may be blocking Tor. Try a different network or check if your ISP blocks Tor traffic.

Hidden Service Creation Failed

This usually means Tor connected but couldn't create the hidden service. The daemon binary may be missing or corrupted.

Terminal
1
2
3
4
5
6
# Reinstall Beam to get fresh daemon binary
npm uninstall -g @byronwade/beam
npm install -g @byronwade/beam
# Check if daemon exists
ls -la $(npm root -g)/@byronwade/beam/bin/

Tor Blocked by Network

Some corporate networks and countries block Tor. If you can't connect from one network but can from another, this is likely the issue.

Beam's embedded Tor client doesn't currently support bridges, but this is planned for a future release. For now, if Tor is blocked:

  • Try a different network (mobile hotspot, VPN)
  • Wait until you're on an unrestricted network
  • Use Beam in local-only mode without Tor for development

DNS Resolution Issues

When using the --domain flag, Beam runs a local DNS server to resolve custom domains. This can sometimes conflict with system DNS settings.

Domain Not Resolving

If myapp.local doesn't resolve after starting the tunnel, your system may not be using Beam's DNS server.

Terminal
1
2
3
4
5
6
7
8
9
# Check if Beam DNS is responding
dig @127.0.0.1 -p 5354 myapp.local
# On macOS, verify resolver is set up
cat /etc/resolver/local
# It should contain:
# nameserver 127.0.0.1
# port 5354

Configuring System DNS (macOS)

Beam tries to configure DNS automatically on macOS, but you may need to do it manually:

Terminal
1
2
3
4
5
6
7
8
9
10
# Create resolver directory if it doesn't exist
sudo mkdir -p /etc/resolver
# Add resolver for .local domains
echo "nameserver 127.0.0.1
port 5354" | sudo tee /etc/resolver/local
# Flush DNS cache
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

Configuring System DNS (Linux)

On Linux, DNS configuration varies by distribution. For systemd-resolved:

Terminal
1
2
3
4
5
6
7
# Add to /etc/systemd/resolved.conf
[Resolve]
DNS=127.0.0.1:5354
Domains=~local
# Restart resolved
sudo systemctl restart systemd-resolved

Alternatively, you can add entries to /etc/hosts manually:127.0.0.1 myapp.local

HTTPS Certificate Issues

When using the --https flag, Beam generates self-signed certificates. Browsers will show warnings because these certificates aren't trusted by default.

Browser Certificate Warning

This is expected behavior for self-signed certificates. In Chrome, click "Advanced" and then "Proceed to site". In Firefox, click "Advanced" and "Accept the Risk and Continue".

For development, you can trust Beam's root certificate to avoid repeated warnings:

Terminal
1
2
3
4
5
6
7
8
# macOS: Add certificate to Keychain
# The certificate is generated at ~/.beam/certs/rootCA.pem
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ~/.beam/certs/rootCA.pem
# Linux (Ubuntu/Debian): Add to system trust store
sudo cp ~/.beam/certs/rootCA.pem /usr/local/share/ca-certificates/beam.crt
sudo update-ca-certificates

Certificate Generation Failed

Certificate generation requires OpenSSL or a compatible library. If generation fails:

Terminal
1
2
3
4
5
6
7
8
9
10
11
# Check if OpenSSL is available
openssl version
# If not installed:
# macOS: comes pre-installed
# Ubuntu/Debian: sudo apt install openssl
# Windows/WSL: sudo apt install openssl
# Clear existing certificates and regenerate
rm -rf ~/.beam/certs
beam 3000 --https --domain myapp.local

Performance Issues

Tor adds latency by design — traffic passes through multiple relays. Typical latency is 200-500ms round-trip. If you're experiencing significantly worse performance, here are some things to check.

High Latency

If latency exceeds 1 second consistently, the Tor circuit may have selected slow relays. Restarting the tunnel creates a new circuit which may be faster.

Terminal
1
2
3
4
5
6
# Stop and restart the tunnel to get new Tor circuits
# Press Ctrl+C, then:
beam 3000
# Use verbose mode to see timing information
beam 3000 --verbose

Requests Timing Out

If requests to your .onion address time out, first verify the tunnel is still running and Tor is connected:

Terminal
1
2
3
4
5
6
7
8
9
10
11
# In the terminal running Beam, you should see:
# "Tunnel active" or similar status messages
# If the process crashed, restart it:
beam 3000 --verbose
# Test local connectivity first:
curl http://localhost:3000
# Then test the .onion address using Tor Browser
# or with curl through a Tor proxy

When Performance Matters

Remember that Tor latency is a tradeoff for privacy. For local development where privacy isn't needed, access your app directly at localhost:3000 or the custom local domain. Use the .onion address only when you need to share access externally or test Tor-specific functionality.

Platform-Specific Issues

macOS

macOS may prompt for permission when Beam tries to accept network connections. Click "Allow" when prompted. If you accidentally denied, you can reset:

Terminal
# Reset network permissions (requires logout)
tccutil reset All
# Or specifically for the terminal app you're using
# System Preferences > Security & Privacy > Firewall > Firewall Options

Linux

On Linux, firewall rules may block Beam. If using ufw:

Terminal
1
2
3
4
5
6
7
8
# Allow Beam's DNS server port
sudo ufw allow 5354/udp
# Allow your application port (if exposing directly)
sudo ufw allow 3000/tcp
# Check firewall status
sudo ufw status

Windows (WSL)

Beam runs in WSL (Windows Subsystem for Linux). Some additional steps may be needed:

Terminal
1
2
3
4
5
6
7
8
9
# Inside WSL, install Beam normally
npm install -g @byronwade/beam
# Windows Firewall may block WSL networking
# Open PowerShell as Administrator:
New-NetFirewallRule -DisplayName "WSL" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow
# If localhost doesn't work from Windows host, use WSL IP:
hostname -I  # Shows WSL IP address

Daemon Issues

Beam includes a compiled Rust daemon that handles Tor integration. Issues with the daemon are usually related to binary compatibility or missing dependencies.

Daemon Failed to Start

If you see "Failed to spawn daemon" or similar errors:

Terminal
1
2
3
4
5
6
7
8
9
10
# Check if the daemon binary exists and is executable
ls -la $(npm root -g)/@byronwade/beam/bin/
# Try running the daemon directly to see errors
$(npm root -g)/@byronwade/beam/bin/beam-tunnel-daemon --help
# If missing or corrupted, reinstall
npm uninstall -g @byronwade/beam
npm cache clean --force
npm install -g @byronwade/beam

Architecture Mismatch

The daemon binary must match your system architecture. On Apple Silicon Macs, make sure you're using the arm64 version:

Terminal
1
2
3
4
5
6
7
8
9
10
11
# Check your architecture
uname -m
# arm64 = Apple Silicon
# x86_64 = Intel
# Check the daemon's architecture
file $(npm root -g)/@byronwade/beam/bin/beam-tunnel-daemon
# If mismatched, clear npm cache and reinstall
npm cache clean --force
npm install -g @byronwade/beam

Getting Help

If you've tried the solutions above and are still having issues, here's how to get help:

Gathering Diagnostic Information

When reporting an issue, include this information:

Terminal
1
2
3
4
5
6
7
8
9
10
11
12
# System information
uname -a
node --version
npm --version
# Beam version
beam --version
# Run with verbose output and save to file
beam 3000 --verbose 2>&1 | tee beam-debug.log
# Include the beam-debug.log contents in your report

Where to Get Help

Related Documentation