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 URL 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 exact URL from the current sender session (URLs change on each restart)
  3. Test connectivity: curl -I https://<tunnel-url> — 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://new-tunnel-url.devtunnels.ms --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 prompt shows an outdated URL or secret (from a previous session).

Cause: The saved receiver-session.json contains stale values.

Resolution — option 1: Override at startup

  cloud-share-receiver --url https://new-url.devtunnels.ms --secret newSecret123

Entering new values overwrites the saved session automatically.

Resolution — option 2: Clear the saved session

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

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