Troubleshooting

Port conflict: 'Port 1355 is already in use'

This error means another process is already listening on the proxy port.Solution:

Stop the existing proxy first:
```
portless proxy stop
```
If that doesn’t work, check what’s using the port:
```
lsof -ti tcp:1355
```
Kill the process manually if needed:
```
kill $(lsof -ti tcp:1355)
```
Restart the proxy:
```
portless proxy start
```

Permission denied for port

Ports below 1024 require root access.Error message:

Permission denied for port 80.

Solution:Either run with sudo for privileged ports:

sudo portless proxy start -p 80

Or use the default non-privileged port (no sudo needed):

portless proxy start  # Uses port 1355 by default

Route conflict: hostname already registered

This happens when you try to run an app with a name that’s already in use by another running process.Error message:

"myapp.localhost" is already registered by a running process (PID 12345).
Use --force to override.

Solutions:

Stop the existing app first, then start yours
Use a different name for your app
Override the existing route with --force:
```
portless myapp --force next dev
```

Safari can't resolve .localhost subdomains

Safari relies on the system DNS resolver, which may not handle .localhost subdomains on all configurations.Symptoms:

Chrome/Firefox/Edge work fine
Safari shows “Safari can’t find the server”

Solution:Add current routes to /etc/hosts (requires sudo):

sudo portless hosts sync

To auto-sync whenever routes change:

export PORTLESS_SYNC_HOSTS=1
sudo portless proxy start

Clean up later:

sudo portless hosts clean

Certificate trust issues / Browser warnings

When using HTTPS, browsers may show certificate warnings if the local CA isn’t trusted.Symptoms:

“Your connection is not private” warning
NET::ERR_CERT_AUTHORITY_INVALID

Solution:Trust the local CA certificate:

sudo portless trust

This adds the portless CA to your system trust store. After this, browsers will trust all portless HTTPS certificates.Supported platforms:

macOS (no sudo required)
Linux (Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, openSUSE)

If portless trust fails, you skipped sudo during first run. Just run it manually as shown above.

508 Loop Detected error

This happens when a dev server proxies requests back through portless without rewriting the Host header.Error message:

508 Loop Detected
This request has passed through portless 5 times.

Common cause: Your frontend dev server (Vite, webpack, etc.) is proxying API requests to another portless app, but isn’t rewriting the Host header.Solution for Vite:

// vite.config.ts
server: {
  proxy: {
    "/api": {
      target: "http://api.myapp.localhost:1355",
      changeOrigin: true,  // Required: rewrites Host header
      ws: true,
    },
  },
}

Solution for webpack-dev-server:

// webpack.config.js
devServer: {
  proxy: [{
    context: ["/api"],
    target: "http://api.myapp.localhost:1355",
    changeOrigin: true,  // Required: rewrites Host header
  }],
}

Proxy not starting automatically

If the proxy doesn’t auto-start when you run an app, it may have failed to start in the background.Solutions:

Check if the proxy is already running:
```
portless list
```
Start the proxy manually to see any errors:
```
portless proxy start --foreground
```

Check the proxy log file:

cat ~/.portless/proxy.log
# or for privileged ports:
cat /tmp/portless/proxy.log

If the proxy PID file is stale:

rm ~/.portless/proxy.pid
portless proxy start

App not accessible at expected URL

Your app is running but not accessible at the portless URL.Troubleshooting steps:

Check if the app registered correctly:
```
portless list
```
Verify the proxy is running:
```
lsof -ti tcp:1355
```
Check if your app is listening on the PORT environment variable:
- Most frameworks (Next.js, Express, Nuxt) respect PORT automatically
- Vite, Astro, React Router, Angular, Expo, React Native: portless auto-injects --port flag

Try accessing the app directly on its assigned port:

curl http://localhost:4123  # Check port from `portless list`

ECONNREFUSED / Bad Gateway (502)

The proxy can’t connect to your app.Error in browser:

502 Bad Gateway
The target app is not responding. It may have crashed.

Common causes:

App crashed - Check your app’s console output
App not listening on PORT - Some apps ignore the PORT env var
Wrong host - App must listen on 127.0.0.1 or 0.0.0.0 (not a specific IP)

Solutions:

Check if the app is actually running:

portless list
# Try to access the app directly:
curl http://localhost:<port-from-list>

For frameworks that ignore PORT, portless auto-injects flags. If this isn’t working:
```
portless myapp --app-port 3000 your-command
```
Check your app’s startup logs for errors

Git worktree prefix not working

Expected a worktree-based subdomain but got the plain name.Symptoms:

In a git worktree on branch feature-auth
Expected: http://auth.myapp.localhost:1355
Got: http://myapp.localhost:1355

Causes:

Using explicit name instead of run:

portless myapp next dev  # Explicit name, no worktree prefix

Use run to enable worktree detection:

portless run next dev  # Auto-detects worktree, adds prefix

Main worktree (main/master branch): The main worktree doesn’t get a prefix. Only linked worktrees do.
Not in a git worktree: Worktree detection only works in git worktrees, not regular branches.

npx/pnpm dlx blocked error

Error message:

Error: portless should not be run via npx or pnpm dlx.

Why: Running sudo npx portless is unsafe because it performs package resolution and downloads as root.Solution:Install portless globally:

npm install -g portless

Then use it directly:

portless proxy start
portless run next dev

PORTLESS=0 not skipping proxy

Setting PORTLESS=0 should run your command directly without the proxy.Make sure you’re using it correctly:

# Correct:
PORTLESS=0 pnpm dev
PORTLESS=skip npm start

# Also works with portless commands:
PORTLESS=0 portless run next dev  # Runs next dev directly

Accepted values:

PORTLESS=0
PORTLESS=skip

Any other value will not skip the proxy.

State directory permissions issues

Errors about file permissions, especially after running with sudo.Common error:

Permission denied: /tmp/portless/routes.json

Cause: When you start the proxy with sudo (for ports < 1024), the state directory is owned by root.Solution:Portless automatically handles this by using world-writable permissions for the system state directory. If you still see errors:

Stop the proxy:
```
sudo portless proxy stop
```

Fix permissions:

sudo chmod 1777 /tmp/portless
sudo chmod 666 /tmp/portless/routes.json

Restart the proxy:
```
sudo portless proxy start
```

OpenSSL not found error

When using HTTPS, portless requires OpenSSL for certificate generation.Error message:

openssl failed: spawn openssl ENOENT
Make sure openssl is installed.

Solution:Install OpenSSL:macOS:

# OpenSSL ships with macOS by default
# If missing, install via Homebrew:
brew install openssl

Debian/Ubuntu:

sudo apt-get install openssl

Arch:

sudo pacman -S openssl

Fedora/RHEL/CentOS:

sudo dnf install openssl

Resources

Common Issues

Getting Help

Debug Mode

Build docs developers (and LLMs) love

Resources

​Common Issues

​Getting Help

​Debug Mode

Build docs developers (and LLMs) love

Common Issues

Getting Help

Debug Mode