Skip to main content
Most Hayate problems fall into a handful of categories: peers not finding each other on the network, connection or timeout issues, firewall rules blocking QUIC’s UDP traffic, and display glitches in certain terminal environments. Work through the accordion items below to diagnose and fix the issue you’re seeing.
Auto-discovery uses mDNS and UDP broadcast. Several network conditions can prevent it from working.
  • Check that both devices are on the same network. mDNS and UDP broadcast are link-local — they don’t cross routers. Both devices must be on the same Wi-Fi network or wired LAN segment.
  • Some routers block multicast traffic. mDNS relies on multicast. If your router has “multicast isolation” or “AP isolation” enabled, discovery will fail. Switch to Direct Mode as a workaround:
  • Corporate and enterprise networks almost always block mDNS. If you’re on a managed network (office, university, hotel), use Direct Mode with explicit IP addresses.
  • Android hotspot mode may isolate connected clients. If one device is sharing a hotspot, clients connected to it may be in an isolated subnet. Connect both devices to the same Wi-Fi router instead.
Hayate uses a QUIC idle timeout of 300 seconds. Very large transfers on slow or congested links may hit this limit.
  • Retry the transfer. Transient congestion clears quickly on most home networks.
  • Keep the receiver running until the transfer is fully complete. Closing the receiver window mid-transfer causes an immediate connection reset.
  • Check for Wi-Fi power saving on mobile devices. Android and iOS can put Wi-Fi radios into a low-power state that introduces multi-second latency spikes. Disable battery saver or keep the screen on during large transfers.
  • Move closer to your router if you’re on Wi-Fi. A weak signal dramatically reduces throughput and increases the chance of hitting the idle timeout.
This error means Hayate couldn’t reach the receiver at the address you specified, or the pairing handshake failed.
  • Confirm hayate receive is running before you send. The receiver must be up and waiting before you run hayate send.
  • Check that the code phrase matches exactly. Code phrases are case-sensitive. Cherry-Blossom and cherry-blossom are different phrases.
  • In Direct Mode, double-check the IP address and port. Copy the address from the receiver’s output rather than typing it manually:
  • Check firewall rules. Hayate uses UDP — specifically QUIC over UDP port 50001 by default. Many firewalls only open TCP by default. See the Windows Firewall section below for platform-specific steps.
On first run, Windows may display a firewall prompt asking whether to allow Hayate through the firewall. Click Allow access and select both private and public networks if needed.If you missed the prompt or if connections are still blocked, create a firewall rule manually using PowerShell (run as Administrator):
If you’re using a non-default port, replace 50001 with your chosen port number. You can verify the rule was created with:
QUIC runs entirely over UDP. Rules that only allow TCP traffic will not help — you must explicitly allow the UDP port Hayate is listening on.
Hayate’s progress bar uses Unicode block characters. Not all terminal emulators render them correctly.
  • Use --no-progress to disable the progress bar entirely. The transfer still completes and the summary is printed normally.
  • On Windows, use Windows Terminal for best Unicode and colour rendering. The legacy cmd.exe console has limited Unicode support.
  • In pipes and scripts, Hayate automatically detects when stdout is not a terminal and hides the progress bar for you — no flag needed.
  • On Termux, some third-party Android terminal apps have partial Unicode support. Try Termux from F-Droid if rendering looks wrong in another app.
By default, received files are saved to the current working directory (.). If Hayate is saving files somewhere unexpected, it’s usually because the terminal’s working directory is not where you expect it to be.
  • Use --output to specify an explicit destination directory:
  • Check your current directory before running hayate receive:
  • The transfer summary printed at the end always shows the full saved path — use it to confirm where the file landed.
A checksum mismatch means the data Hayate received didn’t match what was sent. This is almost always caused by a transient network error.
  • Retry the transfer. Network errors on a LAN are usually momentary.
  • Try --hash sha256 if you keep seeing failures with the default Blake3 hash. SHA-256 is a more conservative choice that may surface different error conditions:
  • Check available disk space on the receiver. Hayate will fail if it runs out of space mid-transfer:
  • Check that the source file isn’t being modified while the transfer is in progress. Sending a file that another process is actively writing to can produce a checksum mismatch.
This error appears during the QUIC/HKDF handshake when the key derived on the sender and receiver don’t match.
  • The code phrase must be identical on both sides. Copy and paste it rather than retyping it.
  • Code phrases are case-sensitive. Forest-River ≠ forest-river — even a single character’s case difference will cause the handshake to fail.
  • Both devices must be running compatible Hayate versions. The handshake protocol is versioned; a major version mismatch will cause key derivation to produce different results. Check versions on both sides:
  • In Direct Mode there is no passphrase — the --code flag is optional and only used as a salt for Pairing Mode. If you’re seeing this error in Direct Mode, make sure you’re not accidentally passing --code on only one side.

​
Still Having Issues?

If none of the above resolved your problem, please open a GitHub issue. Include the output of hayate --version, the operating systems on both sides, and any error messages you see.

Open an Issue on GitHub

Report a bug, ask a question, or request a feature on the Hayate issue tracker.