# How to Interpret MasterDnsVPN Server Logs for Diagnosing Connection Issues

> Learn to interpret MasterDnsVPN server logs and pinpoint connection issues. Understand queue overflows and invalid cookies to diagnose problems effectively.

- Repository: [Amin Mahmoudi/MasterDnsVPN](https://github.com/masterking32/MasterDnsVPN)
- Tags: how-to-guide
- Published: 2026-05-10

---

**MasterDnsVPN emits structured, color-coded log entries that reveal exactly why clients fail to connect, from queue overflows in [`internal/udpserver/server_runtime.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/udpserver/server_runtime.go) to invalid cookie thresholds in [`server_session.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/server_session.go).**

MasterDnsVPN is a UDP-based VPN server that outputs detailed diagnostic information during startup, connection handling, and error conditions. Learning how to interpret these server logs allows you to distinguish between network congestion, configuration limits, and stale session data without guessing. This guide walks through the specific log sources in the `masterking32/MasterDnsVPN` repository and explains how to correlate log patterns with configuration parameters to resolve connection failures.

## Understanding the Logging Infrastructure

The logging system is implemented in [`internal/logger/logger.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/logger/logger.go) and formats every entry with a timestamp, optional color tag, component name, and severity level.

The four log levels you will encounter are:

- **`Debugf`** – Detailed internal state messages, including invalid-session drops and packet parsing details
- **`Infof`** – Normal operational events such as startup banners and successful session creation
- **`Warnf`** – Abnormal but recoverable conditions like queue overloads or socket buffer failures
- **`Errorf`** – Fatal misconfigurations that prevent the server from operating, such as encryption key errors

When the server writes logs to a file, color tags are automatically stripped, leaving plain text that remains fully searchable with standard Unix tools like `grep` or `awk`.

## Startup and Configuration Logs

### Server Initialization Messages

When the binary launches, [`cmd/server/main.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/cmd/server/main.go) emits a startup banner at lines 101-107 that confirms the process is healthy:

```text
🚀 MasterDnsVPN Server starting …
GitHub: https://github.com/masterking32/MasterDnsVPN
Build Version: …

```

If you do not see this banner, the binary failed before reaching the logging initialization. Verify the log level in your configuration—if set higher than `INFO`, these messages are suppressed.

### UDP Listener Configuration

After startup, [`internal/udpserver/server.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/udpserver/server.go) logs the UDP stack configuration at lines 309-316:

```text
📡 UDP Listener Ready, Addr: …, Readers: N, Workers: M, Queue: Q, Sockets: S

```

This line reveals four critical tuning parameters:
- **Readers** – Goroutines reading from the UDP socket
- **Workers** – Goroutines processing packets (controlled by `DNS_REQUEST_WORKERS` in [`server_config.toml`](https://github.com/masterking32/MasterDnsVPN/blob/main/server_config.toml))
- **Queue** – Channel buffer capacity for incoming requests (defaults to `MAX_CONCURRENT_REQUESTS`)
- **Sockets** – Number of bound UDP sockets

If the Queue value reads at its maximum (e.g., `512/512`), the server is already under load and approaching packet drops.

## Connection Lifecycle Logs

### Session Creation Success

Successful handshakes trigger a log entry in [`internal/udpserver/server_session.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/udpserver/server_session.go) at lines 179-229:

```text
✅ Session Created, ID: 3, Mode: RAW, Upload Compression: ZLIB, …

```

This confirms the client completed the `PACKET_SESSION_INIT` handshake. If this log never appears but you see inbound packets, check:
- `MAX_ALLOWED_CLIENT_ACTIVE_SESSIONS` may be reached
- Domain filtering rules might block the client before session allocation

### Session Validation Failures

When a packet fails session validation, `logInvalidSessionDrop` at lines 92-118 of [`server_session.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/server_session.go) emits one of two patterns:

**Unknown Session:**

```text
🔶 Sending Session Drop | Reason: unknown session | Session: 7 | Received: 12 | Mode: RAW

```

**Invalid Cookie Threshold:**

```text
🔶 Sending Session Drop | Reason: invalid cookie threshold | Session: 7 | Expected: 8 | Received: 12 | Mode: BASE64

```

These indicate:
- The client reused an old session ID after a server restart
- Packet loss caused the cookie sequence to desynchronize
- An attacker is flooding random cookies, triggering `INVALID_COOKIE_ERROR_THRESHOLD` (default typically 5)

### Session Teardown

Graceful disconnections appear as:

```text
🛑 Session Closed By Client, Session: 3

```

If sessions accumulate without corresponding close logs, inspect `SESSION_TIMEOUT_SECONDS` and verify the cleanup ticker in [`internal/udpserver/server_runtime.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/udpserver/server_runtime.go) is running. Missing cleanup logs indicate the `sessionCleanupLoop` is disabled or the timeout interval is set too high.

## Performance and Overload Indicators

### Request Queue Overload

The most common cause of "connection timed out" complaints appears in [`internal/udpserver/server_runtime.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/udpserver/server_runtime.go) at lines 57-80:

```text
⚠️ Request Queue Overloaded | Dropped: 123 | Queue: 512/512 | Remote: 1.2.3.4:12345

```

This warning fires when the inbound request channel reaches capacity. The server discards UDP packets immediately, before session logic processes them.

To resolve this bottleneck:
1. Increase `MAX_CONCURRENT_REQUESTS` in [`server_config.toml`](https://github.com/masterking32/MasterDnsVPN/blob/main/server_config.toml)
2. Raise `DROP_LOG_INTERVAL_SECONDS` to reduce log noise while dropping
3. Verify OS-level socket buffer sizes (`socket_buffers` in the config) are sufficient for your network throughput

### Deferred Session Backpressure

DNS and SOCKS5 CONNECT packets are queued for deferred processing in [`internal/udpserver/deferred_session.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/udpserver/deferred_session.go). When this queue saturates, you will see overload messages similar to the request queue warnings.

This indicates:
- Upstream DNS latency is causing backups
- SOCKS5 proxies are responding slowly

Mitigate by increasing `DEFERRED_SESSION_WORKERS` or `DEFERRED_SESSION_QUEUE_LIMIT`, or switch to faster upstream DNS endpoints.

## Encryption and Security Errors

Before any UDP processing begins, [`cmd/server/main.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/cmd/server/main.go) validates the AES encryption setup. Failures appear as:

```text
❌ Encryption Key Setup Failed | …
❌ Encryption Codec Setup Failed | …

```

These **Errorf** level logs halt the server. Verify the file path specified in `ENCRYPTION_KEY_PATH` is readable by the process user, or check disk space if the server auto-generates keys.

## Practical Log Analysis Examples

The following Go snippets demonstrate how to programmatically inspect server state using the same patterns found in the source code.

Detecting queue overload programmatically:

```go
// Check if packets are being dropped
if s.droppedPackets.Load() > 0 {
    total := s.droppedPackets.Load()
    log.Warnf(
        "⚠️ %d packets dropped due to full request queue – check MAX_CONCURRENT_REQUESTS",
        total,
    )
}

```

Adjusting cookie tolerance at runtime:

```go
// Raise threshold to tolerate out-of-order packets after network hiccups
s.invalidCookieThreshold = 10 // default is 5

```

Enabling debug output for deep inspection:

```go
// Replace standard logger with DEBUG level
log := logger.New("MasterDnsVPN Server", "debug") // instead of "info"

```

Retrieving drop statistics for diagnostics:

```go
func (s *Server) lastDropInfo() string {
    return fmt.Sprintf(
        "Last drop: %d packets, last log at %v",
        s.droppedPackets.Load(),
        time.Unix(0, s.lastDropLogUnix.Load()),
    )
}

```

## Summary

- **Startup confirmation** appears in [`cmd/server/main.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/cmd/server/main.go) with the rocket emoji banner—verify this first to ensure you are tailing logs from a running process
- **Queue overload** warnings in [`internal/udpserver/server_runtime.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/udpserver/server_runtime.go) directly explain client timeouts and require tuning `MAX_CONCURRENT_REQUESTS` or OS socket buffers
- **Invalid cookie drops** in [`internal/udpserver/server_session.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/udpserver/server_session.go) reveal desynchronized clients or potential attacks, adjustable via `INVALID_COOKIE_ERROR_THRESHOLD`
- **Session creation logs** confirm successful handshakes; their absence points to `MAX_ALLOWED_CLIENT_ACTIVE_SESSIONS` limits or domain filters
- **Deferred session** backpressure indicates slow upstream DNS or SOCKS5 proxies, resolvable by increasing `DEFERRED_SESSION_WORKERS`

## Frequently Asked Questions

### Why do I see "Request Queue Overloaded" errors butlow CPU usage?

This indicates the UDP receive buffer in the kernel or the application's request channel is the bottleneck, not processing power. According to [`internal/udpserver/server_runtime.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/udpserver/server_runtime.go) lines 57-80, packets are dropped when the `MAX_CONCURRENT_REQUESTS` channel fills before worker goroutines can drain it. Increase `MAX_CONCURRENT_REQUESTS` in [`server_config.toml`](https://github.com/masterking32/MasterDnsVPN/blob/main/server_config.toml) and verify `socket_buffers` settings in the OS match your network throughput.

### What does "invalid cookie threshold" mean in the logs?

This message from [`internal/udpserver/server_session.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/udpserver/server_session.go) lines 92-118 signifies the server received a packet with a cookie sequence number that deviates too far from the expected value. It commonly occurs when a client resumes after a network pause, causing out-of-order delivery, or during cookie-flood attacks. You can raise the tolerance by adjusting `INVALID_COOKIE_ERROR_THRESHOLD` in your configuration, or reduce client-side ping aggressiveness via `CLIENT_MIN_PING_AGGRESSIVE_INTERVAL`.

### How do I enable DEBUG logging to see every dropped packet?

Initialize the logger with the debug level as shown in [`internal/logger/logger.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/logger/logger.go). Replace your existing logger initialization with `logger.New("MasterDnsVPN Server", "debug")` to receive `Debugf` output including granular session validation failures and packet handler traces. Remember to revert to `info` level in production to prevent disk exhaustion from high-volume UDP traffic.

### Why aren't expired sessions being cleaned up?

If [`internal/udpserver/server_runtime.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/udpserver/server_runtime.go) shows the cleanup loop running but finding no sessions, verify `SESSION_TIMEOUT_SECONDS` is not set to an excessively high value. Additionally, ensure `SESSION_CLEANUP_INTERVAL_SECONDS` is greater than zero; if set to zero or if the cleanup ticker is disabled, zombie sessions accumulate indefinitely, consuming memory and preventing new connections under `MAX_ALLOWED_CLIENT_ACTIVE_SESSIONS` limits.