Skip to content

Troubleshooting

Jump to bottom
Next1971 edited this page Sep 6, 2026 · 2 revisions

Troubleshooting

This page provides a safe first-pass checklist for common MASQUE VPN deployment and connectivity problems.

For exact installation commands, supported versions, configuration formats, and client-specific behavior, use the versioned documentation in the main repository and the notes for the release you are using.

Important

Never post private keys, client certificates, complete configuration bundles, access tokens, or unredacted logs in a public issue or discussion.

Start with the basics

Before changing configuration, record:

  • MASQUE VPN server version or release tag.
  • Client application version.
  • Client platform and operating-system version.
  • VPS provider and operating-system version.
  • Whether the problem occurs on Wi-Fi, mobile data, or both.
  • The approximate time of the failed attempt, including timezone.
  • The exact user-visible error message.
  • Whether the deployment worked previously and what changed before it stopped.

Then check the latest release and its release notes. A client/server version mismatch or a recently changed configuration format can explain behavior that looks like a network failure.

Fast isolation checklist

Use this order to avoid changing many variables at once:

  1. Confirm that the server is online and that you can still administer the VPS.
  2. Confirm that the MASQUE VPN server process is running.
  3. Confirm that the client uses the intended server endpoint.
  4. Confirm that the client credentials belong to the expected deployment.
  5. Confirm that the required server firewall and provider firewall rules are present.
  6. Test the same client from a different network, if possible.
  7. Test another authorized client against the same server, if available.
  8. Check whether the failure began after a client, server, operating-system, firewall, DNS, or VPS-provider change.
  9. Review sanitized server and client logs around the recorded failure time.
  10. Search existing project issues and discussions.

Make one change at a time and record its result. This makes regressions and network-specific failures much easier to identify.

Connection will not establish

If the client cannot establish a connection:

  • Check that the hostname or IP address in the client configuration is correct.
  • Verify that the server is reachable from the client network.
  • Confirm that the server process is listening on the intended endpoint.
  • Check host-level firewall rules and VPS-provider firewall or security-group rules.
  • Confirm that the network path allows the UDP traffic required by your deployment.
  • Check DNS resolution if the client uses a hostname.
  • Verify that the client date and time are reasonably accurate; certificate validation can fail with a substantially incorrect clock.
  • Verify that the client trusts the expected server identity.
  • Test from another Wi-Fi network or a mobile network to distinguish a server-side failure from a local-network restriction.

Do not assume that a successful connection from one network proves universal reachability. Enterprise Wi-Fi, captive portals, mobile operators, roaming networks, and regional filtering can handle UDP traffic differently.

Authentication or certificate errors

Authentication failures often indicate a mismatch between the client credentials and the server's expected trust configuration.

Check that:

  • You imported the intended client credential set.
  • The client certificate and private key are still present and readable by the client application.
  • The client credential has not been replaced, revoked, or regenerated.
  • The client is connecting to the intended server, not an older endpoint.
  • The server certificate and client trust configuration still match.
  • The device clock is correct enough for certificate validity checks.
  • Recent server-side changes did not replace the certificate authority, server certificate, or authorized-client set.

Do not “fix” certificate errors by disabling verification, accepting an unexpected identity, or sharing credentials publicly for inspection.

If you must replace credentials, use the current release-specific procedure and securely remove obsolete credentials from devices that no longer need them.

Connected, but traffic does not work

If the client reports that it is connected but browsing or applications fail:

  1. Confirm whether the problem affects all traffic or only selected apps or destinations.
  2. Test a simple HTTPS site and a direct IP-based destination, if appropriate, to help distinguish DNS from general routing problems.
  3. Check the intended tunnel routing rules and whether any traffic is designed to bypass the VPN.
  4. Verify server IP forwarding, routing, and egress configuration according to the current server documentation.
  5. Check whether the VPS itself has working outbound connectivity.
  6. Check DNS resolver configuration and observe whether names resolve as expected.
  7. Consider IPv4 and IPv6 separately; one address family may work while the other does not.
  8. Test from another network to identify local filtering or DNS interference.
  9. Review client and server logs for routing, DNS, or tunnel errors.

Do not publish destination addresses, browsing history, DNS logs, account identifiers, or other sensitive traffic information when seeking help.

Slow, unstable, or intermittent connections

Performance and stability are affected by the entire path between the client, server, and destination.

Check:

  • Signal quality and packet loss on the local network.
  • Whether the issue occurs only on Wi-Fi, only on mobile data, or on both.
  • VPS CPU, memory, disk, and network usage.
  • VPS-provider rate limits, traffic shaping, quotas, or incidents.
  • Server-region distance from the client and the destination.
  • Changes in MTU, path behavior, NAT, or local-network equipment.
  • Client and server logs for reconnects, timeouts, or repeated failures.
  • Whether the issue occurs with one client only or with multiple clients.
  • Review MTU Testing when symptoms suggest PMTU, fragmentation, retransmission, or network-specific UDP-path differences.

Test with a simple comparison: the same client and server from two different networks. If only one network fails, preserve that observation rather than immediately changing the server configuration.

DNS problems

Symptoms of DNS problems can include websites failing to open while direct IP connections work, intermittent name resolution, or different behavior across networks.

Check:

  • Which DNS resolver the deployment is intended to use.
  • Whether DNS requests follow the expected route.
  • Whether the client has a conflicting system, enterprise, browser, or application-specific DNS setting.
  • Whether IPv4 and IPv6 DNS behavior differs.
  • Whether the problem appears only on one local network.
  • Whether a captive portal or network-policy system is intercepting DNS.

Avoid sharing complete DNS logs publicly. They can expose domains you visited, internal hostnames, or network topology.

Server is running, but no client can connect

If every authorized client fails:

  • Verify that the server is still reachable at the expected address.
  • Check the server service status and recent logs.
  • Review recent operating-system, firewall, package, certificate, or network changes.
  • Verify inbound UDP handling at both the VPS-provider and host-firewall layers.
  • Confirm that the public IP address or DNS record has not changed.
  • Check certificate and client-authorization material for unintended changes.
  • Verify that the VPS is not suspended, rate-limited, out of quota, or under a provider-level network restriction.

If the service stopped after an upgrade, compare the installed client and server versions with the release notes before rolling back or making broad configuration changes.

One network fails, another works

This usually points to a network-path difference rather than a universal server failure.

Record:

  • The network type: home Wi-Fi, enterprise Wi-Fi, public Wi-Fi, or mobile data.
  • The country or region only if you are comfortable sharing it.
  • Whether a captive portal is present.
  • Whether ordinary UDP-based applications work on that network.
  • Whether the issue is stable, time-dependent, or intermittent.
  • Whether a different client device has the same result on that network.

Review the project's censorship resistance documentation for reachability context and limitations. Do not assume that any protocol guarantees operation across every filtered or restricted network.

Collecting useful logs

When reporting a problem, collect only information relevant to the failure and sanitize it before sharing.

A useful report generally includes:

  • Server and client versions.
  • Client platform and operating-system version.
  • VPS operating system and general provider context.
  • Approximate failure time and timezone.
  • Network type and whether another network works.
  • Exact visible error text.
  • Steps that reliably reproduce the issue.
  • What you expected to happen and what happened instead.
  • Sanitized log excerpts around the failure.

Remove or redact:

  • Private keys, certificate bodies, and credential bundles.
  • Tokens, passwords, and secrets.
  • Full client configuration files.
  • Personal IP addresses, hostnames, and device identifiers unless essential.
  • DNS history, browsing history, account identifiers, and unrelated log data.

Before opening an issue

Use this checklist:

For a suspected security vulnerability, do not open a public issue. Follow the repository security policy.

Related pages

Clone this wiki locally