Help

Troubleshooting

Run the diagnostic, then check the matching issue below.

Run the diagnostic

pwrp doctor
pwrp daemon status
pwrp ps --once

pwrp doctor checks login, Portwarp connectivity, daemon compatibility, local configuration access, and local service reachability without changing your settings.

Command not found

• Close and reopen the terminal after installing.
• Run the executable from its folder to confirm that the downloaded file works.
• Confirm that the folder containing pwrp or pwrp.exe is in your PATH.
• On Linux and macOS, confirm that the file is executable with chmod +x pwrp.

Login does not complete

Leave pwrp login running while you open the displayed URL and enter the current code. Codes are temporary; restart the command if it expired.

pwrp login
pwrp status

If the browser does not open automatically, copy the URL shown in the terminal into any browser where you can sign in to Portwarp.

The tunnel connects but the service is down

A live tunnel and a reachable local service are separate checks. If pwrp ps shows the local service as down:

1. Confirm that the application or game server is running.
2. Confirm that it listens on the same local port configured for the tunnel.
3. If the service runs on another machine, verify the saved target and local network firewall.
4. Restart the tunnel after changing its target or local service configuration.

pwrp target list
pwrp restart <tunnel>
pwrp logs <tunnel> --tail 50

Tunnel is already running elsewhere

Lease-managed tunnels allow only one executor. Stop the tunnel on its current device, or submit an explicit handoff through the dashboard/API. Handoff is never automatic. If you see upgrade_required, update this client before retrying.

Remote command is not delivered

Run pwrp remote status and pwrp daemon status. The device must be online, remote control must be enabled locally, and the Portwarp client must be up to date. Actions sent to an unavailable device fail immediately.

If the status command reports that the feature is not available for the account, wait until access is enabled. Local tunnel sessions and lease renewal continue normally.

A tunnel cannot be owned by two devices at the same time. Stop it on the other device before connecting here. If the other device is no longer available, wait for its stale session to expire and try again.

The daemon is not responding

Restarting the daemon reconnects tunnels that were saved for startup:

pwrp daemon restart
pwrp daemon status
pwrp doctor

If restart cannot reach the old daemon, use pwrp daemon stop and run pwrp connect again.

Docker service name does not resolve

• Make sure the pwrp service and target service share at least one Compose network.
• Use the Compose service name or a network alias, not the container's public URL.
• Make sure the target container is running.
• Reconnect the tunnel after changing a target.

docker compose ps
docker compose exec pwrp pwrp target list
docker compose exec pwrp pwrp connect <tunnel> --detach
docker compose logs -f pwrp

Targets that resolve only to public, link-local, multicast, or metadata addresses are intentionally rejected.

Startup does not reconnect tunnels

Check that a selection is saved and native startup is enabled:

pwrp config get boot-all
pwrp config get boot-tunnels
pwrp service status

Save again with pwrp connect --all --save --detach. In Docker, confirm the named volume is still mounted and the service has a restart policy.

Update problems

Run pwrp doctor to check version status and connectivity. Native installations update with pwrp update. Docker installations update by replacing the image:

docker compose pull pwrp
docker compose up -d pwrp

Still need help?

Collect the output of pwrp doctor, the relevant lines from pwrp logs, your operating system, and the CLI version. Do not share login tokens or passwords. Then contact the Portwarp community on Discord.