Skip to Content
🎉 Portal 0.11.0 is released. Read more →
Troubleshooting

Troubleshooting

Discovery search times out

The sender wraps discovery in a 30-second timeout. If you see a timeout or the receiver is never found:

  • confirm both devices are on the same local network
  • confirm the receiver actually started portal receive
  • confirm you are targeting the exact configured username
  • fall back to direct IP mode if multicast discovery is unreliable on your network

Receiver fails before listening

The receiver depends on config more than the old docs suggested. It needs:

  • a username in config
  • a port from either --port or network.default_port

If either of those is missing, run portal config setup or set the missing keys manually.

Directories are rejected on send

If you pass a directory without -r, the sender fails intentionally. Add the recursive flag:

portal send -r path/to/folder

Partial transfers show up in history

That is expected behavior. Both send and receive paths write failed history records too, including partial byte counts when available. This is useful because it tells you a transfer started and how far it got before failing.

Receiver save location is not what you expected

The receiver chooses its target directory in this order:

  1. --dir
  2. storage.download_dir from config
  3. an interactive prompt that defaults to ~/Downloads

If downloads are landing in the wrong place, inspect config first:

portal config show storage.download_dir

Logs

Portal creates session log files under:

~/.portal/_logs/
  • Terminal log defaults to warn.
  • Use -v to raise terminal logs to info.
  • Use -q to reduce terminal logs to error.
  • PORTAL_LOG is preferred over RUST_LOG if both are set.
  • File logs default to debug when neither env variable is set.
  • PowerShell: $env:PORTAL_LOG="debug"; portal send ...
  • Bash: PORTAL_LOG=debug portal send ...
  • PowerShell (fallback): $env:RUST_LOG="debug"; portal send ...
  • Bash (fallback): RUST_LOG=debug portal send ...

If output is too noisy:

  • use portal -q ... for terminal-only quiet mode
  • or set PORTAL_LOG=error to reduce log-file verbosity

If output is too quiet:

  • use portal -v ... for more terminal detail
  • or set PORTAL_LOG=debug / PORTAL_LOG=trace for deeper diagnostics

History file location

Transfer history is stored separately from the log files in:

~/.portal/history.jsonl

That matters because log files are session-oriented, while history is transfer-oriented.

CLI to CLIFAQ