Connection refused / receiver cannot connect

Symptom: The receiver shows:

  Error: Connection refused

or the queue never loads and the status badge shows Disconnected.

Cause: One of several things:

  1. The sender is not running
  2. The wrong tunnel ID, region, or port was entered
  3. The Dev Tunnel has expired (sender was stopped and restarted with a new URL)
  4. A firewall is blocking *.devtunnels.ms:443

Resolution:

  1. Verify the sender is running and shows a tunnel URL in its output
  2. Confirm the receiver is using the tunnel ID/region/port from the current sender session (tunnel ID changes on each restart)
  3. Test connectivity: curl -I https://<tunnel-id>.<region>.devtunnels.ms:<port> — you should get a 200 or 401 response
  4. Check your firewall allows outbound HTTPS to *.devtunnels.ms:443

If you restarted the sender, start the receiver fresh with the new URL and secret:

  cloud-share-receiver --url https://mtszwr0l.uks1.devtunnels.ms:5000 --secret newSecret123
# or using shorthand:
cloud-share-receiver --code mtszwr0l.uks1:5000 --secret newSecret123

Wrong secret / 401 Unauthorized

Symptom: The receiver UI shows an authentication error, or API calls return:

  401 Unauthorized

Cause: The secret entered in the receiver does not match the current sender session.

Resolution:

  1. Check the sender terminal output for the correct secret
  2. Re-enter the secret in the receiver:
      cloud-share-receiver --url https://<tunnel-url> --secret <correct-secret>
  3. If the sender was restarted, it has a new secret — get the new one from the sender output

ℹ️ Info: The secret changes every time the sender is restarted. Saved sessions in receiver-session.json may have an outdated secret.

Hash mismatch error

Symptom: After clicking Receive, the hash verification modal shows:

  ❌ Hash mismatch — content may have been tampered with

Cause: The SHA-512 hash of the decrypted content does not match the hash computed by the sender. This is rare in normal operation.

What happened:

  • The item has been permanently deleted from the sender queue
  • The decrypted content was discarded and not saved

Resolution:

  1. Ask the sender to re-queue the item (re-share the text, re-upload the file)
  2. If this happens repeatedly for the same content, it may indicate a network corruption issue — try running the sender with --log verbose to investigate

⚠️ Warning: A hash mismatch cannot be retried on the same queued item. It must be re-sent from scratch.

Receiver session shows wrong URL/secret

Symptom: The receiver startup history shows an outdated entry or the history SelectionPrompt pre-selects a stale tunnel.

Cause: The saved receiver-session.json contains entries from a previous sender session.

Resolution — option 1: Select “Connect to a new tunnel…” in the history prompt and enter the new tunnel ID, region, and port. The new connection is saved and the stale entry is replaced.

Resolution — option 2: Pass the new URL directly at startup

  cloud-share-receiver --url https://mtszwr0l.uks1.devtunnels.ms:5000 --secret newSecret123
# or shorthand:
cloud-share-receiver --code mtszwr0l.uks1:5000 --secret newSecret123

Entering new values overwrites the saved session automatically.

Resolution — option 3: Clear the entire session history

  # Windows
del "%APPDATA%\CloudShare\receiver-session.json"

# macOS / Linux
rm ~/.config/CloudShare/receiver-session.json