> ## Documentation Index
> Fetch the complete documentation index at: https://e-gurl.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions for common DNS-MNS issues

# Troubleshooting

This page covers common issues and their solutions.

## Installation Issues

### "Command not found: dns-mns"

The command was not added to your PATH.

**Solutions:**

1. Restart your terminal
2. Run directly: `~/.local/bin/dns-mns`
3. Add to PATH manually:
   ```bash theme={null}
   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   ```

<Tip>
  If you use the pre-built binary instead, just run it directly -- no PATH setup needed.
</Tip>

### "curl: command not found"

Install curl, use wget instead, or use the pre-built binary which doesn't need curl at all.

**Use the binary (recommended for Iran):**

Download from the [Releases page](https://gitlab.com/E-Gurl/dns-mns/-/releases) -- no curl/wget needed.

**Or install curl:**

**Ubuntu/Debian:**

```bash theme={null}
sudo apt install curl
```

**Or use wget:**

```bash theme={null}
wget -qO- https://gitlab.com/E-Gurl/dns-mns/-/raw/main/install.sh | bash
```

### "Permission denied" during installation

Make the script or binary executable:

```bash theme={null}
chmod +x install.sh
# Or for the binary:
chmod +x dns-mns-linux-amd64
```

## DNS Testing Issues

### All DNS servers show as unreachable

**Possible causes:**

* No internet connection
* Firewall blocking ICMP
* ISP blocking DNS queries

**Solutions:**

1. Check your internet connection:
   ```bash theme={null}
   ping google.com
   ```

2. Try a known working DNS:
   ```bash theme={null}
   ping 1.1.1.1
   ```

3. Check if your firewall is blocking:
   ```bash theme={null}
   sudo iptables -L | grep icmp
   ```

### Testing is very slow

**Possible causes:**

* Many DNS servers are unreachable
* Slow internet connection
* High network latency

**Solutions:**

1. Test a specific category instead of all servers
2. Ensure you have a stable connection
3. Close bandwidth-heavy applications

### "dig: command not found"

The `dig` command is optional but improves testing accuracy.

**Ubuntu/Debian:**

```bash theme={null}
sudo apt install dnsutils
```

**Fedora:**

```bash theme={null}
sudo dnf install bind-utils
```

**macOS:**

```bash theme={null}
brew install bind
```

## DNS Configuration Issues

### "Permission denied" when changing DNS

The tool needs administrator privileges.

**Linux/macOS:**

```bash theme={null}
sudo dns-mns
```

**Windows:**
Right-click Git Bash or PowerShell and select "Run as Administrator"

### DNS changes not taking effect

**Step 1:** Flush DNS cache

<Tabs>
  <Tab title="Linux">
    ```bash theme={null}
    sudo resolvectl flush-caches
    ```
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    Clear-DnsClientCache
    ```
  </Tab>
</Tabs>

**Step 2:** Verify DNS is set

<Tabs>
  <Tab title="Linux">
    ```bash theme={null}
    resolvectl status
    # Or
    cat /etc/resolv.conf
    ```
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    scutil --dns
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    Get-DnsClientServerAddress
    ```
  </Tab>
</Tabs>

**Step 3:** Restart network service

<Tabs>
  <Tab title="Linux">
    ```bash theme={null}
    sudo systemctl restart systemd-resolved
    # Or
    sudo systemctl restart NetworkManager
    ```
  </Tab>

  <Tab title="macOS">
    Toggle Wi-Fi off and on, or:

    ```bash theme={null}
    sudo ifconfig en0 down && sudo ifconfig en0 up
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    Restart-NetAdapter -Name "Wi-Fi"
    ```
  </Tab>
</Tabs>

### DNS changes don't persist after reboot

**Linux (NetworkManager):**

```bash theme={null}
sudo nmcli connection modify "Your Connection" ipv4.ignore-auto-dns yes
```

**Linux (systemd-resolved):**
Ensure the config file exists:

```bash theme={null}
cat /etc/systemd/resolved.conf.d/dns-mns.conf
```

### VPN overrides DNS settings

Most VPNs override DNS settings for security. Options:

1. Configure DNS within your VPN client
2. Disconnect VPN before changing DNS
3. Use VPN's DNS servers instead

## General Issues

### Tool shows old version

Update to the latest version using the built-in updater:

```bash theme={null}
dns-mns update
```

Or re-run the installer to download the latest binary:

```bash theme={null}
curl -sSL https://gitlab.com/E-Gurl/dns-mns/-/raw/main/install.sh | bash
```

### Colors not displaying correctly

Your terminal may not support ANSI colors.

**Solutions:**

1. Use a modern terminal emulator
2. Set TERM environment variable:
   ```bash theme={null}
   export TERM=xterm-256color
   ```

## Network Issues

### Websites still not loading after DNS change

**Possible causes:**

* DNS cache not flushed
* Browser cache
* ISP-level blocking

**Solutions:**

1. Flush DNS cache (see above)
2. Clear browser cache
3. Try incognito/private browsing
4. Restart browser

### Gaming ping still high

DNS only affects name resolution, not game server routing.

**Additional steps:**

1. Use a gaming VPN (ExitLag, WTFast)
2. Check your ISP's routing
3. Use wired instead of Wi-Fi
4. Close background applications

### Some websites work, others don't

The DNS server may be blocking certain domains.

**Solutions:**

1. Try a different DNS (e.g., Cloudflare 1.1.1.1)
2. Use option 3 to reset DNS and test

## System Diagnostics

Use the built-in diagnostics command to automatically check your system configuration:

```bash theme={null}
dns-mns diagnose
```

This checks:

* System information and OS version
* Administrator/root permissions
* Network interface configuration
* Current DNS settings
* DNS resolution capabilities
* Platform-specific configuration

**Save diagnostics to a file:**

```bash theme={null}
dns-mns diagnose > dns-mns-debug.txt
```

Include this output when opening bug reports.

## Windows-Specific Issues

### "Access Denied" Errors

**Problem:** Windows requires Administrator privileges to change DNS settings.

**Solutions:**

1. **Use the PowerShell Wrapper (Recommended):**
   ```powershell theme={null}
   .\dns-mns-wrapper.ps1
   ```
   Download from the releases page and place next to `dns-mns.exe`.

2. **Manual Elevation:**
   Right-click PowerShell and select "Run as Administrator"

### Update Process on Windows

Windows locks running executables, which prevents direct replacement. The updater handles this automatically by:

1. Downloading the new binary to a temporary file
2. Creating an update script (`update.bat` and `update.vbs`)
3. Exiting the current process
4. The script replaces the binary and restarts the application

**Note:** You may see `update.bat` or `update.vbs` files temporarily during updates. These are cleaned up automatically after successful completion.

### Antivirus False Positives

Some antivirus software may flag DNS-MNS because it modifies network settings. This is a false positive.

**If your antivirus blocks the tool:**

1. Add an exception for `dns-mns.exe` in your antivirus settings
2. Windows Defender typically does not flag the tool

### PowerShell Execution Policy

**Error:** `Execution of scripts is disabled on this system`

**Solution:** Run PowerShell as Administrator and execute:

```powershell theme={null}
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

## Getting Help

If you're still experiencing issues:

1. **Run diagnostics:** `dns-mns diagnose > debug.txt`
2. **Check existing issues:** [gitlab.com/E-Gurl/dns-mns/issues](https://gitlab.com/E-Gurl/dns-mns/issues)
3. **Open a new issue** with:
   * Your operating system and version
   * The command you ran
   * The error message you received
   * Output of `dns-mns diagnose`

```bash theme={null}
# Capture output for bug report
dns-mns diagnose 2>&1 | tee dns-mns-debug.log
```