Skip to main content
This guide covers common issues you might encounter when deploying ScaleTail services and how to resolve them.

​
Service not appearing in Tailscale admin console

The service container starts but doesn’t appear in your Tailscale admin console.Check Tailscale logs:
docker logs tailscale-servicename
Verify Tailscale status:
docker exec tailscale-servicename tailscale status
Cause: The TS_AUTHKEY is invalid, expired, or already used (without reusable flag).Fix:
  1. Generate a new auth key in the Tailscale admin console
  2. Enable the Reusable option
  3. Update your .env file: 
    TS_AUTHKEY=tskey-auth-xxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  4. Restart the service: 
    docker compose down
docker compose up -d
Cause: The /dev/net/tun device isn’t available on the host.Verify device exists:
ls -l /dev/net/tun
Fix for Linux:
# Load the tun module
sudo modprobe tun

# Make it persistent across reboots
echo "tun" | sudo tee -a /etc/modules
Fix for WSL2:
# In PowerShell (run as Administrator)
wsl --install
wsl --update
Then restart WSL:
wsl --shutdown

​
Health check failures

Symptoms: Tailscale container marked as unhealthyTest the health endpoint:
docker exec tailscale-servicename wget -O- http://127.0.0.1:41234/healthz
Expected output:
{"healthy":true}
Common fixes:
  • Verify TS_ENABLE_HEALTH_CHECK=true is set
  • Verify TS_LOCAL_ADDR_PORT=127.0.0.1:41234 is set
  • Check Tailscale has authenticated: 
    docker exec tailscale-servicename tailscale status
  • Wait for the start_period to elapse (default 10s)
Symptoms: Application container marked as unhealthyDebug the health check:
# Run the health check command manually
docker exec app-servicename pgrep -f servicename

# Check application logs
docker logs app-servicename
Common fixes:
  • Increase start_period for slow-starting services: 
    healthcheck:
  start_period: 60s
  • Verify the process name matches the health check command
  • Check if the application requires additional configuration before starting

​
DNS resolution issues

Symptoms: Cannot access service via MagicDNS hostname (servicename.your-tailnet.ts.net)Solution:
  1. Enable MagicDNS in your Tailscale admin console
  2. Add TS_ACCEPT_DNS=true to your Tailscale container: 
    tailscale:
  environment:
    - TS_ACCEPT_DNS=true
  3. Restart the service: 
    docker compose restart tailscale
Symptoms: Application container cannot resolve external domainsSolution: Add a DNS server to your compose.yaml:
tailscale:
  dns:
    - 1.1.1.1
    - 8.8.8.8
Or use your .env file:
DNS_SERVER=1.1.1.1
Then in compose.yaml:
tailscale:
  dns:
    - ${DNS_SERVER}

​
Network connectivity problems

Symptoms: Can access service via localhost but not via Tailscale IPVerify Tailscale connectivity:
# Get the Tailscale IP
docker exec tailscale-servicename tailscale ip -4

# From another device on your Tailnet, ping the service
ping 100.x.x.x
Check Serve configuration:
# Verify Serve is configured
docker exec tailscale-servicename tailscale serve status
Verify serve.json configuration:
configs:
  ts-serve:
    content: |
      {"TCP":{"443":{"HTTPS":true}},
      "Web":{"${TS_CERT_DOMAIN}:443":
          {"Handlers":{"/":
          {"Proxy":"http://127.0.0.1:8096"}}}},  # Verify port matches your service
      "AllowFunnel":{"${TS_CERT_DOMAIN}:443":false}}
Symptoms: Funnel enabled but service not accessible publiclyVerify Funnel is enabled:
  1. Check AllowFunnel in serve.json: 
    "AllowFunnel":{"${TS_CERT_DOMAIN}:443":true}
  2. Enable Funnel in the admin console
  3. Restart the service: 
    docker compose restart tailscale
Test Funnel status:
docker exec tailscale-servicename tailscale funnel status

​
Permission errors

Symptoms: Application cannot write to mounted volumesError in logs:
Permission denied: '/config/settings.json'
Solution: Fix directory ownership:
# Stop the service
docker compose down

# Fix ownership (use your user ID)
sudo chown -R $USER:$USER ./servicename-data

# Set proper permissions
chmod -R 755 ./servicename-data

# Restart the service
docker compose up -d
For PUID/PGID services:
# Find your user and group IDs
id

# Add to .env file
echo "PUID=$(id -u)" >> .env
echo "PGID=$(id -g)" >> .env

# Restart
docker compose up -d
Symptoms: Cannot connect to Docker daemonError:
permission denied while trying to connect to the Docker daemon socket
Solution:
# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and back in for changes to take effect
# Or run:
newgrp docker

# Verify
docker ps

​
Port binding conflicts

Symptoms: Cannot start service due to port conflictError:
Error starting userland proxy: listen tcp 0.0.0.0:8096: bind: address already in use
Find the conflicting process:
# Linux
sudo lsof -i :8096

# Or with netstat
sudo netstat -tulpn | grep :8096
Solution: Either:
  1. Stop the conflicting service
  2. Change the port in your compose.yaml
  3. Comment out the ports section if you only need Tailscale access: 
    #ports:
#  - 0.0.0.0:${SERVICEPORT}:${SERVICEPORT}

​
Configuration issues

Symptoms: Variables like ${SERVICE} appear literally in container namesVerify .env file exists:
ls -la .env
cat .env
Validate configuration:
# Check if variables are substituted
docker compose config | grep container_name
Solution: Ensure .env file is in the same directory as compose.yaml
Symptoms: Tailscale Serve not working, service not accessible on port 443Check if serve.json is mounted:
docker exec tailscale-servicename cat /config/serve.json
Verify TS_SERVE_CONFIG is set:
docker exec tailscale-servicename env | grep TS_SERVE_CONFIG
Expected output:
TS_SERVE_CONFIG=/config/serve.json
Solution: Verify the configs section in compose.yaml:
configs:
  ts-serve:
    content: |
      {"TCP":{"443":{"HTTPS":true}}, ...}

services:
  tailscale:
    configs:
      - source: ts-serve
        target: /config/serve.json

​
Resource issues

Symptoms: Container crashes or OOM (Out of Memory) errors in logsAdd memory limits:
services:
  application:
    deploy:
      resources:
        limits:
          memory: 4G
        reservations:
          memory: 2G
Symptoms: Cannot write files, containers failing to startCheck disk usage:
df -h
docker system df
Clean up Docker resources:
# Remove unused containers, networks, images
docker system prune -a

# Remove unused volumes (CAREFUL - this deletes data)
docker volume prune

​
Getting help

GitHub Issues

Report bugs or request features

Tailscale Support

Get help with Tailscale-specific issues

Community

Ask questions and share experiences

Documentation

Review the quickstart guide

​
Diagnostic commands

Use these commands to gather information when troubleshooting: 
# Docker and system info
docker --version
docker compose version
uname -a

# Container status
docker compose ps
docker compose logs --tail=100

# Tailscale status
docker exec tailscale-servicename tailscale status
docker exec tailscale-servicename tailscale ip

# Network connectivity
docker exec tailscale-servicename ping -c 3 8.8.8.8
docker exec tailscale-servicename nslookup google.com

# Resource usage
docker stats --no-stream
df -h
free -h

Build docs developers (and LLMs) love

Get started for freeTalk to us