Find the failing layer first.

Five-minute triage

1. Is internet access working without the VPN? Complete captive portals and stabilize the base network first.
2. Is another VPN active? Disconnect it; do not run two system tunnels during diagnosis.
3. Does subscription refresh work? If no, diagnose provider/Remnawave/HWID before the tunnel.
4. Can one known-good route connect manually? If yes, diagnose Smart Route candidates/quality. If no, diagnose the tunnel/provider route.
5. Is the symptom user-only, network cohort, app release or provider-wide? Use only qualified aggregate evidence.
6. Was there a recent change? Pause it and compare with the last known good state.

Subscription will not import or refresh

Wrong, missing or stale provider branding

1. Confirm exactly one X-NODIF-Provider-ID and one X-NODIF-Branding-Token reach the client.
2. Confirm the ID is the public slug, not the tenant UUID.
3. Check for legacy X-UMMA-* aliases or differently cased duplicates.
4. Verify the token belongs to the same provider and has not been revoked.
5. Check active Brand entitlement and approved production profile.
6. Confirm device time; signed profiles expire and are rejected when invalid.
7. Check that logo/link validation passes. A rejected asset should fall back safely rather than break the entire app.
8. If a provider attempted self-service profile/logo PUT, expect 409 branding_review_required; submit through NODIF moderation while the current approved profile stays live.

Analytics is empty

1. Call GET /v1/provider/session and check analytics_read, analytics_entitled, subscription state and policy.
2. Confirm users separately opted in. VPN functionality does not depend on consent.
3. Wait for devices that were offline to reconnect and upload their encrypted queue.
4. Try the overview for a seven-day window before a narrow hourly/city view.
5. Remember each bucket/row independently needs the dynamic minimum install count.
6. Check coverage: context or catalog dimensions can remain unknown/empty even when overview metrics exist.
7. Keep query within raw retention, with RFC 3339 UTC timestamps and from < to.

Do not lower the privacy threshold, query overlapping slices to infer a group, or treat suppression as missing telemetry.

Provider portal/API errors

The updated portal displays the safe error code and request ID. Copy the incident reference, never the key or response body containing one-time credentials.

Windows tunnel failures

“Adapter did not become ready”

1. Disconnect other VPNs and stop conflicting virtual-network/filter software.
2. Verify supported Windows architecture and current NODIF build.
3. Check the expected tunnel adapter is present/enabled.
4. Retry with required service/admin privileges if policy permits.
5. Reboot after driver/network-stack updates.
6. Escalate the coded stage/time if repeatable.

“Could not configure the TUN interface address”

1. Check for duplicate/static route or address conflicts.
2. Confirm endpoint security/firewall did not block interface configuration.
3. Do not randomly delete all network adapters or use a full network reset first.
4. Test a clean controlled Windows profile/device to isolate local corruption versus app/provider behavior.

“Tunnel did not finish starting in time”

1. Separate route-probe success from tunnel startup; a reachable server can still fail tunnel establishment.
2. Check provider route/protocol, system adapter readiness and security software.
3. Avoid repeated “Optimize route” clicks while a connection attempt is active.
4. Capture coded startup stage, not a raw process dump containing arguments/configuration.

Android connection drops or permission failures

1. Confirm Android’s VPN permission was accepted and another always-on/lockdown VPN is not owning the tunnel.
2. Complete captive portal login before connecting.
3. Allow background operation and review aggressive battery restrictions if the OS kills NODIF.
4. Test Wi‑Fi and mobile separately; allow recovery after a handoff.
5. Check provider subscription/HWID state after app reinstall or device change.
6. If sideloaded, verify the official APK hash and update only from NODIF.

Connection is slow or unstable

1. Measure the base network without VPN and note network type/time—do not expect the VPN to exceed a congested link.
2. Run Check routes first. Use Speed test intentionally because it consumes data and can interrupt.
3. Compare latency, jitter, loss, throughput and handshake together; do not choose by ping alone.
4. Test one manual route to distinguish Smart Route ranking from provider path quality.
5. Look for a qualifying network/platform/protocol cohort rather than assuming one user represents a city/ISP.
6. Check provider capacity and recent routing/balancer changes.
7. Avoid route flapping: switching too often can be worse than a slightly slower stable route.

HWID failures

Escalate safely

Include impact, UTC start/last-good, app version/build, platform/OS major/architecture, network type, stable error code/stage, API request ID, redacted recent change, canary/rollback result and reproduction steps. Exclude all subscription URLs/tokens, provider/admin/branding keys, HWIDs, raw configurations, host/domain/IP lists, packet captures, browsing and DNS history.