Troubleshooting Common Errors

Cannot Connect to LocalXpose Servers

When LocalXpose cannot reach our servers, troubleshoot these potential causes:

1. Firewall Blocking Port 54536

LocalXpose requires outbound TCP port 54536. Test connectivity:

# Test if port 54536 is open
telnet portquiz.net 54536

If this fails, configure your firewall to allow outbound connections on port 54536.

2. DNS Resolution Issues

Your network may be blocking or filtering DNS queries. Test DNS resolution:

# Linux/macOS
dig us.loclx.io
nslookup us.loclx.io
 
# Windows
nslookup us.loclx.io

What to look for:

• You should receive an IP address in the response
• If you get "NXDOMAIN" or no response, your DNS is likely filtered
• Compare results using different DNS servers:

# Test with Google DNS
nslookup us.loclx.io 8.8.8.8
 
# Test with Cloudflare DNS
nslookup us.loclx.io 1.1.1.1

If public DNS servers work but your default doesn't, change your DNS settings (opens in a new tab) to use Cloudflare (1.1.1.1) or Google (8.8.8.8).

3. ISP or Network Blocking

If both port and DNS tests pass but connections still fail, your ISP or corporate network may be blocking LocalXpose traffic. Solutions:

• Try using a VPN service
• Contact your network administrator
• Use a mobile hotspot to test if the issue is network-specific

Docker-Specific Errors

GUI Not Accessible in Docker

The GUI binds to localhost by default, which isn't accessible outside the container.

Solution: Set the bind address to allow external connections:

docker run -e LX_ACCESS_TOKEN \
    -e HTTP_LISTEN_ADDRESS=0.0.0.0:54537 \
    -p 54537:54537 \
    localxpose/localxpose:latest gui

Why this works: HTTP_LISTEN_ADDRESS=0.0.0.0:54537 makes the GUI listen on all interfaces instead of just localhost.

HTTPS Stopped Working After Container Restart

This occurs when Let's Encrypt rate limits are exceeded. Without persistent storage, each container restart requests a new certificate.

Solution: Always mount a volume to persist certificates:

docker run -v ./lx-data:/home/nonroot/.localxpose \
    -e LX_ACCESS_TOKEN \
    localxpose/localxpose:latest tunnel http

Rate Limit Recovery:

• Limit: 5 certificates per domain per 7 days
• Wait time: 34 hours between additional requests after hitting the limit
• Testing tip: Use test subdomains (e.g., test.yourdomain.com) to preserve production quota
• Full reset: 7 days after the first certificate was issued

OCI Runtime Error or "loclx: command not found"

This happens when using incompatible Docker image versions.

Version Differences:

Solution: Pin to a specific version:

# For new deployments (recommended)
docker run localxpose/localxpose:24.1.1 tunnel http
 
# For legacy compatibility
docker run localxpose/localxpose:23.11.1 tunnel http

Cannot Connect to Host Services from Docker

Docker containers have isolated networks - localhost inside a container doesn't reach your host machine.

Solutions by Platform:

Docker Desktop (Mac/Windows)

docker run -e LX_ACCESS_TOKEN \
    localxpose/localxpose:latest \
    tunnel http --to host.docker.internal:8080

Linux

# Option 1: Use host IP
HOST_IP=$(hostname -I | awk '{print $1}')
docker run -e LX_ACCESS_TOKEN \
    localxpose/localxpose:latest \
    tunnel http --to $HOST_IP:8080
 
# Option 2: Host network mode
   ```shell copy
   docker run --network host \
       -e LX_ACCESS_TOKEN \
       localxpose/localxpose:latest \
       tunnel http --to localhost:8080

Permission Denied When Accessing Volumes

Version 24.1.1+ runs as nonroot user (UID 65532) which may lack permissions for mounted directories.

Solution:

# Create directory and set permissions
mkdir -p ./lx-data
 
# Option 1: Make accessible to all (quick fix)
chmod 777 ./lx-data
 
# Option 2: Set specific ownership (more secure)
sudo chown 65532:65532 ./lx-data
 
# Run with mounted volume
docker run -v ./lx-data:/home/nonroot/.localxpose \
    localxpose/localxpose:latest

HTTP/1.0 Protocol Errors with Node.js

Node.js 22+ may reject HTTP/1.0 responses from LocalXpose.

Workarounds:

• Use Node.js 20 LTS (recommended)
• Use an HTTP client library that supports HTTP/1.0
• Configure your client to accept HTTP/1.0 responses

Note: This is a known issue being addressed in future releases.

Need More Help?

• See our comprehensive Docker guide
• Contact support at hello@localxpose.io
• Check service status (opens in a new tab)