Troubleshooting guide (tunnel start failures)

Read this alongside the "Tunnel status and failure reasons" section of the user guide. When a tunnel card shows the red "Failed" state, first click "Copy error info" on the card to get the failure summary, then work through the paths below.

Common failure categories

Start failures are mapped to the categories below (the card shows readable text, not raw logs):

§1 Authentication failure

Symptom: The failure summary contains "authentication failed / invalid token / unauthorised", or the server returns 401.

What to do:

1. Sign in again (sign out, then sign back in to refresh the local token) and start the tunnel.
2. Make sure the account still has access to that tunnel (is the node disabled? is the account in arrears or banned?).
3. If it happens often, check that the system clock is correct (a large offset breaks token signature validation).
4. If it still fails: copy the error info, add your account and node details and send feedback.

§2 Port in use

Symptom: The failure summary contains "port already in use / address already in use".

What to do:

1. Check that the remote port is not taken by another tunnel (a given remote port on a node can only be assigned to one tunnel).
2. Check that the local port is not taken by another program on your machine (for example port 80 held by IIS/nginx).
   • Windows: netstat -ano | findstr :PORT to find the owning process.
   • Linux/macOS: lsof -i :PORT or ss -ltnp | grep PORT.
3. Once you know what holds it: stop that program, or pick a different port when creating/editing the tunnel.

§3 Node unreachable

Symptom: The failure summary contains "cannot connect / connection refused / node unreachable", or there is no online confirmation within 30 seconds (timeout).

What to do:

1. Use "Refresh latency test" on the tunnel management page to check whether the node is reachable (latency / timeout / failure).
   • Timeout: the node is overloaded or the network is unstable. Retry later, or use another node.
   • Failure (connection refused): the node may be offline or may not expose that port.
2. Check your local network: can you reach other sites/services? Is a proxy/VPN interfering with the connection to the node?
3. Check whether your local firewall or security software is blocking mefrpc's outbound connections.

§4 Process crashed

Symptom: The failure summary contains "process exited abnormally (exit code N)".

What to do:

1. Check whether the mefrpc version is compatible with the node's server (the Update page shows the latest version; re-download the client if needed).
2. Look at the output just before the crash: run the same start command manually on the Terminal page and watch where it errors.
3. A corrupted configuration file can also cause a crash: delete the matching temporary config under Config/frp and retry.
4. If it still crashes: copy the error info (including the exit code) and send feedback.

§5 Unknown errors

Symptom: The failure summary is the raw API error message.

What to do:

1. The summary usually contains the raw server response; search for those keywords or report it directly.
2. Paste the whole "Copy error info" content (app version + mefrpc version + summary) into your feedback.

General advice

• Before reporting anything, always use "Copy error info" on the card — it includes the app and mefrpc versions, which speeds up diagnosis enormously.
• After changing your network environment (proxy, DNS, firewall), run "Refresh latency test" again to verify connectivity before starting the tunnel.

Certificate request failures (26.4)

The "Certificate assistant" is built on lego's DNS-01 flow and offers two verification methods (see "Certificate assistant → Verification method" in the user guide): DNS account (one-click automatic), where the app calls your DNS provider's API to read and write the TXT record for you, and manual DNS, where you add the TXT record yourself.

lego download failure (the certificate component cannot be prepared)

• Symptom: After clicking "Start request" the app stays on "Preparing lego…" for a long time, or reports "Cannot prepare the lego certificate component (download or verification failed)".
• Cause: The network cannot reach GitHub (the primary source) or the fallback mirror, or the downloaded content fails verification.
• What to do: Check your network and proxy, then retry. The app tries the primary and fallback sources in turn; a verification failure usually means an incomplete download, so retrying is enough. If it never works, switch to the "manual DNS" mode (it still needs lego — only the verification method differs).

Manual DNS: stuck on "Add the TXT record and continue"

• This is a normal waiting state (only in manual mode): the app is waiting for you to add the TXT record at your DNS provider. It will not time out on its own.
• What to do: Copy the "record host" and "record value" from the window into your DNS console (type TXT), save, then click "I have added it".
• If you close the window by mistake, the request is cancelled (the lego process is terminated). Just request again.

DNS account (one-click automatic) failures

In automatic mode the app already has the provider's explicit error, so the UI text usually states the cause:

While the request runs, the window shows a live "runtime log" (sanitised lego output). When it fails you can expand it to pinpoint the cause.

Common manual-DNS failures

The certificate is set but the tunnel still fails to start

• A Staging certificate cannot be used in production: Staging certificates are not trusted by browsers and exist only to validate the flow. Request a Production certificate for real use.
• The certificate and private key do not match: use the fullchain.pem and privkey.pem produced by the same request; "Select from certificate assistant" fills them in as a pair, which avoids manual mistakes.
• Expiry reminders: selecting a Staging certificate shows "Staging (test)"; any other certificate less than 30 days from expiry shows "Expiring soon (N d)".

What's new window (26.4)

The window says "Update notes are temporarily unavailable"

• Symptom: After upgrading, the first start shows "What's new", but the content area says "Update notes are temporarily unavailable; you can check the Update page later.".
• Cause: The update API is unreachable (network/proxy), or the server has no entry for the current version yet.
• What to do: Check your network, then visit the "Update" page for the full changelog. A failure here does not affect startup and the window is not shown again as a retry.
• The "Blog updates" tab fails to load: same as above — it reports a fetch failure. Switch back to the "Changelog (API)" tab or use the Update page.

Don't want it to pop up again

• Once shown, the window counts as read (recorded in Cache/whats-new.json), so the same version will not interrupt you twice, and it never appears when the version number has not changed.

Update failures

Failed to fetch update information

Symptom: The "Update" page status area shows "Failed to fetch updates" with no latest version.

What to do:

1. Check your network (can you reach other sites?) and whether a proxy/VPN blocks requests to the update API.
2. Click "Check for updates" to retry. If the update channel is "Preview", switch back to "Stable" and try again (the preview channel occasionally has no release).

Download failure / verification failure

Symptom: The status area shows "Update download failed…" or "Downloaded file failed verification…" with a "Retry download" button.

What to do:

1. Click "Retry download" once (network glitches are common).
2. If it still fails, switch the download source (TPCA ↔ Official) on the Settings page and retry.
3. If verification keeps failing after a retry, the source file may be corrupt: wait a while and retry, or switch download sources.
4. On Windows, if the download is an installer, make sure there is enough disk space (installers are hundreds of MB, and the Cache directory needs room).

The mefrpc download fails when starting a tunnel for the first time

Symptom: Starting a tunnel reports that the mefrpc client could not be downloaded, and the tunnel does not start.

What to do:

1. Check whether bin/mefrpc.exe (Windows) or bin/mefrpc.tar (Linux/macOS) exists; when missing, starting a tunnel downloads it automatically.
2. If the download fails, switch the download source (TPCA ↔ Official) on the Settings page and start the tunnel again.
3. If verification fails (corrupt file), delete the leftover mefrpc*.tmp and damaged files under bin and retry.

Starting a tunnel from a link (pml2://)

The app supports pml2:// universal links, so a browser or web page can start a specific tunnel in one click:

pml2://StartProxy/<tunnel ID>?Name=<tunnel name>

(The mefrp:// prefix is recognised too. Name is optional; without it the terminal tab shows #<tunnel ID>.)

Platform differences on first use

Registration happens once, when the primary instance starts. If the application directory is moved or reinstalled, the next start rewrites it to the new path.

What clicking a link does

• The app is not running (cold start): the link parameters are written to Cache/startup.json and the main window picks them up within 2 minutes to start that tunnel (the temporary file is deleted immediately after reading, so the tunnel is not started twice).
• The app is already running: the second instance passes the link through to the running instance (named pipe tech.rycb.pml2), which shows the main window and starts the tunnel.

Clicked the link and nothing happened?