Muddog troubleshooting

On the Connection screen, first determine whether the problem affects your VPN connection or Internet sharing. Look for the cause in the corresponding Connection details, or in Error details within an error notification.

Symptom	What to check
Service unavailable	Service status and access permissions
Empty country list or connection failure	Countries and peer connections
Connected, but the IP is unchanged or sites cannot be reached	VPN traffic settings
App launch button unavailable or some apps bypass the VPN	Per-app VPN
Error saying the service does not support a feature	App and service versions
Only internet sharing fails	Sharing and log storage

Service unavailable

The app reads the background service's status and displays it. This message means the app cannot check the status; it does not confirm that the VPN or sharing has stopped.

The app reconnects automatically when the service recovers. Check the service status and permissions for your operating system below. Starting the service also starts internet sharing.

Linux

1. If you just installed Muddog, log out of your desktop, log back in, and open the app.

2. Check the service status in a terminal.

   systemctl status muddog-engine.service --no-pager

3. If the service is stopped and you want to resume VPN use and sharing, start it. Internet sharing also resumes when the service starts.

   sudo systemctl start muddog-engine.service

4. If the service is running but the app cannot access it, run id -nG in a terminal under the account that uses the app and check for the muddog group.

If the group is missing because an administrator installed Muddog from another account, run the following command in a terminal logged in as the regular user who will use the app. Then log out of your desktop and log back in.

sudo usermod -aG muddog "$(id -un)"

Do not substitute running the app as an administrator. If the service itself will not start, check recent errors with:

sudo journalctl -u muddog-engine.service -n 100 --no-pager

Windows

Check the service status in PowerShell:

Get-Service -Name muddog-engine

If the service is stopped, start it in PowerShell running as an administrator:

Start-Service -Name muddog-engine

If you disabled the service, follow the instructions to enable automatic startup again. If the service or required files are missing, install or repair Muddog using the latest MSI. Run the app as a regular user.

macOS

1. Check that you are using macOS 13 or later and have copied Muddog.app to /Applications.
2. Check that you are logged in with a macOS administrator account.
3. Select Service → Enable Background Service to request service registration.
4. Open Service → Background Service Settings… and allow Muddog to run in the background. After approval, wait for the app to reconnect to the service.

You can also check the registered service's status in a terminal:

sudo launchctl print system/net.3rocks.muddog.engine

Running the app from the DMG or another folder prevents service registration. If problems started after you replaced the existing app, follow the macOS update procedure to remove the service, then reopen the app.

If the steps above do not resolve the problem, include the service errors in a problem report.

Empty country list or connection failure

1. Check that your regular internet connection works.
2. Under Destination, click Refresh list.
3. If your selected country has disappeared from the list, use Automatic or another country.
4. If you changed the connection server, restore and save the advanced settings defaults.
5. If the connection still fails, check Connection details.

P2P connections depend on participants in the selected country and the network conditions at both ends. A listed country does not guarantee a connection. If no peer is available, try again later or choose another country. You can also compare with another available internet connection to check whether firewall or router restrictions are the cause.

Ten attempts is the maximum, and the process may end sooner if no peer can be found. If an established VPN disconnects, you must reconnect manually.

Connected, but the IP is unchanged or sites are unreachable

1. On the Connection screen, check that the current traffic mode is the one you intended. If you saved settings without reconnecting, the previous mode still applies.
2. In IP/range mode, check whether the destination IP you want to access is included in or excluded from the list. Domain names cannot be entered in the address list.
3. In per-app mode, fully close the app and launch it again through Muddog.
4. Check whether the connection you are testing uses IPv6. IPv6 does not pass through the VPN, and per-app mode on Windows blocks IPv6 traffic from selected apps.
5. If you use another VPN or network management tool, compare the result with that connection disabled. Routes set by other tools may take priority.

If the browser or IP check page is outside the VPN's scope, seeing your regular connection's IP address is expected. DNS may also use your regular connection depending on the selected mode and the DNS server's IP address.

If a website's country restriction persists, try another country or peer. Muddog does not guarantee access to a particular service or a specific speed.

On macOS, disconnect and reconnect the VPN after changing your active network connection, such as Wi-Fi. If IP inclusion mode reports a conflict with a host route set by another program, check that program's connection and the IP addresses and ranges you specified.

Per-app VPN does not apply

• Per-app VPN is not supported on macOS. Use all internet traffic or IP/range mode instead.
• If Launch with VPN is disabled, check that you saved per-app mode, connected to the VPN in that mode, and selected an app to launch.
• If the app list is empty, use Refresh list or Browse for executable.
• If a browser only reopens an existing window, stop its background processes before launching it again.
• Apps that delegate execution to a separate service or reuse an existing instance are not supported. Check the installation method and per-app VPN requirements.
• On Linux, Snap and Flatpak apps are not supported. For errors involving the systemd user session, cgroup v2, or nftables, check those parts of your environment and include Error details in a problem report.
• On Windows, select the .exe file to launch. After reconnecting the VPN, fully close the program and launch it again from Muddog.
• If Windows reports that a WinDivert component is missing or cannot be loaded, repair or reinstall Muddog using the MSI. If it still fails, report the Error details.

App and service versions do not match

Connecting to an older service that does not support a feature requested by the app causes an error. Update both the app and the service with the new package. Per-app VPN is unavailable on macOS because of the platform's supported feature set, not a version mismatch.

If the error remains after updating, restart the service using the instructions for your operating system. Restarting interrupts active personal VPN and sharing connections.

On Linux, close the app, run the following command, then reopen the app:

sudo systemctl restart muddog-engine.service

On Windows, close the app, run the following command in PowerShell as an administrator, then reopen the app:

Restart-Service -Name muddog-engine

On macOS, select Service → Remove Background Service and Quit, then reopen Muddog from /Applications and complete any required service approval.

You must reconnect the VPN after restarting the service. If the error continues, report the app version and error details instead of repeatedly restarting.

Internet sharing fails or logs cannot be read

First check Internet sharing → Connection details. Sharing stops if there is insufficient log storage space, the storage limit is exceeded, or a file write fails. Logs follow the local retention policy.

Check disk space and service logs. If you need the retained records, do not delete them just to clear the error. Request support with the error message instead.

If only log searches fail, check service access permissions and the service version. If daily log cleanup changed records during a search, select the date and filters again and click Search. If a search succeeds but returns no results, check the UTC date, filters, and Next records.