11. Troubleshooting

Daftar Isi

1. 11.1 Diagnostic toolkit
2. 11.2 Helper Service tidak respond
3. 11.3 Tunnel tidak handshake
4. 11.4 Tunnel up tapi internet tidak jalan
5. 11.5 SaseConfigClient: “user_data.configuration kosong”
6. 11.6 SaseConfigClient: “user_data row not found”
7. 11.7 Helper RPC error code -32001 (“Caller not authenticated”)
8. 11.8 Helper RPC error -32000 (validation failed)
9. 11.9 Helper RPC error -32002 (OS operation failed)
10. 11.10 Performance: tunnel bandwidth rendah
11. 11.11 macOS: notarization issues
12. 11.12 Reconnect loop
13. 11.13 “Config refresh tidak trigger”
14. 11.15 Diagnostic checklist untuk support ticket
15. 11.16 Eskalasi

---

11.1 Diagnostic toolkit

# Lokal (Win / Mac sama)
wg show
wg show Hermes latest-handshakes
wg show Hermes transfer
ping <internal-IP-yang-ada-di-AllowedIPs>
curl https://ifconfig.me   # IP harus IP gateway

# Helper alive check (named pipe / unix-socket)
# Kirim Ping JSON-RPC manual via test program

# Supabase query test
curl "$SUPABASE_URL/rest/v1/user_data?select=configuration,assigned_ip,sase_slice_id,sase_version" \
  -H "apikey: $ANON" -H "Authorization: Bearer $JWT"

Lokasi log:

Apa	Windows	macOS
Hermes UI app	%LOCALAPPDATA%\HermesNetwork360Guard\app.log	~/Library/Logs/HermesNetwork360Guard/app.log
Hermes Helper	Event Viewer → Application (Source: HermesHelperSvc)	/var/log/hermes-helper.{out,err}.log
WireGuard tunnel	Event Viewer → Application (Source: WireGuard)	(none — Helper log)

11.2 Helper Service tidak respond

Gejala: _helper.PingAsync() throw timeout atau “pipe not found”.

Penyebab	Cara cek	Fix
Helper Service belum terinstall	sc query HermesHelperSvc (Win) / launchctl list com.hermesnetwork.helper (Mac)	Reinstall via installer
Helper Service crash	Event Viewer / /var/log/hermes-helper.err.log	Cek error, fix bug, restart
Pipe / socket permission salah	Win: accesschk -p HermesHelperSvc / Mac: ls -la /var/run/hermes-helper.sock	Restart Helper, pastikan permission setup di startup
UI binary tidak signed	Helper authentication reject	Sign UI binary dengan cert yang sama

Diagnosa step-by-step:

# Windows
sc query HermesHelperSvc
# Expected: STATE: 4 RUNNING

Get-EventLog -LogName Application -Source HermesHelperSvc -Newest 20

# Test pipe manual
$pipe = New-Object IO.Pipes.NamedPipeClientStream(".", "HermesHelper", "InOut")
$pipe.Connect(2000)   # 2-second timeout

# macOS
sudo launchctl list com.hermesnetwork.helper
# Look for "PID" > 0

sudo tail -50 /var/log/hermes-helper.err.log

# Test socket
nc -U /var/run/hermes-helper.sock < /dev/null

11.3 Tunnel tidak handshake

Gejala: wg show peer ada, tapi latest-handshake kosong / sangat lama.

Penyebab	Cek	Fix
Firewall block UDP 51820 outbound	nc -uvz <gateway> 51820	Whitelist gateway endpoint
PublicKey client tidak ter-register di gateway	Extract PublicKey dari configuration (grep PublicKey), compare dengan list peer di gateway dashboard	Eskalasi ke admin tooling untuk re-generate configuration user atau register ulang peer
PSK mismatch	(tidak ada cara langsung)	Refresh config dari Supabase
Endpoint IP berubah / DNS resolve gagal	nslookup <gateway-host>	wg-quick down && up (force re-resolve)
MTU terlalu besar	ping -M do -s 1372 <gw>	Set MTU = 1280 di config
NAT timeout	Tidak ada keepalive	PersistentKeepalive = 25

Diagnosa:

# UDP test
nc -uvz <gateway-host> 51820

# Tcpdump (Mac/Linux)
sudo tcpdump -i any -n udp port 51820 -vv

# Manual reconnect
sudo wg-quick down /etc/wireguard/Hermes.conf
sudo wg-quick up /etc/wireguard/Hermes.conf

11.4 Tunnel up tapi internet tidak jalan

Penyebab	Cek	Fix
AllowedIPs tidak cover destination	wg show Hermes allowed-ips	Eskalasi ke admin: minta admin update user_data.configuration user dengan AllowedIPs yang sesuai. Client tidak UPDATE field ini.
Routing tidak ke tunnel interface	route get 8.8.8.8 (Mac) / Get-NetRoute (Win)	Restart tunnel
MTU drop packet	ping -M do -s 1400 8.8.8.8	Set MTU 1280
DNS broken	nslookup example.com	Verify DNS line di config
Gateway-side block	Test ke IP allowed dulu	Hubungi ops

11.5 SaseConfigClient: “user_data.configuration kosong”

Gejala: GetConfigAsync() throw “user_data.configuration kosong” atau “tidak terlihat seperti WireGuard INI”.

Penyebab: Row user_data user belum di-populate dengan configuration valid.

Fix:

1. Verify dengan query:

   -- read-only — JANGAN UPDATE
   SELECT length(configuration), substring(configuration for 80) AS preview
   FROM user_data WHERE uid = '<auth-user-uuid>';
   

2. Kalau NULL atau kosong → koordinasi dengan ops untuk populate configuration. Client TIDAK menulis field ini.
3. Kalau ada tapi format bukan INI WireGuard → minta ops fix admin tooling yang generate config

11.6 SaseConfigClient: “user_data row not found”

Penyebab:

• User profile belum ter-create
• RLS policy salah
• JWT user invalid / expired

Fix:

-- Verify row exists
SELECT * FROM user_data WHERE id = '<user-uuid>';

-- Verify RLS policy
SELECT polname, qual FROM pg_policies WHERE tablename = 'user_data';

Kalau row hilang, create dulu (via trigger di auth.users atau manual):

INSERT INTO user_data (id) VALUES ('<user-uuid>') ON CONFLICT DO NOTHING;

11.7 Helper RPC error code -32001 (“Caller not authenticated”)

Penyebab: Caller authenticator reject — caller tidak punya identity yang valid.

Diagnosa:

• Apakah UI binary signed dengan cert yang Helper trust?
• Apakah caller running dengan user identity yang dikenal?

Fix:

• Sign ulang UI binary dengan cert yang sama dengan Helper
• Verify policy di CallerAuthenticator (mungkin terlalu ketat)

11.8 Helper RPC error -32000 (validation failed)

Penyebab: Input gagal validation:

• Tunnel name regex mismatch
• Config tidak ada [Interface] atau [Peer] section
• Config terlalu besar (>16 KiB)

Fix:

• Cek config string yang di-pass ke ApplyConfig
• Pastikan format INI valid (kalau pakai JSON di Supabase, parser converted ke INI)
• Log config dengan PrivateKey + PSK redacted untuk debug

11.9 Helper RPC error -32002 (OS operation failed)

Penyebab: Operasi OS gagal — Service.Add / Service.Remove (embedded TunnelDll) throw, wg-quick (Mac) error, sc access denied, dll.

Diagnosa: Lihat error.data di response — biasanya forward stderr dari command yang gagal.

Fix tergantung error message:

• “Access denied” → Helper tidak running as SYSTEM/root → reinstall service
• “DLL not found: tunnel.dll” → tunnel.dll (Windows) atau wireguard-go (Mac, di Contents/MacOS/{arch}/) tidak ter-deploy benar; rebuild + reinstall app. WG embedded di project, bukan external installer.
• “Service already exists” → uninstall existing tunnel dulu sebelum install ulang

11.10 Performance: tunnel bandwidth rendah

Gejala: Speed via tunnel jauh di bawah speed normal.

speedtest-cli                            # tanpa tunnel
sudo wg-quick up /etc/wireguard/Hermes
speedtest-cli                            # dengan tunnel

Cause	Fix
MTU mismatch	Set MTU = 1280
CPU encryption (laptop low-end)	(hardware limit)
Gateway overload	Hubungi ops
Routing path tidak optimal	Multi-region gateway selection (advanced)

11.11 macOS: notarization issues

Issue	Fix
Reject “Hardened runtime not enabled”	Re-sign dengan --options runtime
Reject “Code object is not signed at all”	Sign semua dylib + executable + Helper binary di bundle
Reject “Invalid signature”	Verify identity, regenerate p12 kalau perlu
spctl reject signed app	Run xcrun stapler staple setelah notarization

11.12 Reconnect loop

Gejala: UI status flicker antara Connecting/Reconnecting/Faulted.

Penyebab: Config tidak valid, gateway intermittent, atau monitor logic terlalu agresif.

Diagnosa:

# Manual stable test (bypass monitor):
sudo wg-quick down /etc/wireguard/Hermes
sudo wg-quick up /etc/wireguard/Hermes
watch -n 1 'wg show Hermes latest-handshakes'

Kalau manual stable tapi via app tidak → bug di logic MonitorLoopAsync. Tambah verbose logging.

11.13 “Config refresh tidak trigger”

Gejala: Admin update user_data.configuration di Supabase, tapi user tidak terapply.

Penyebab:

• Tab SASE belum dibuka (monitor active hanya saat connected)
• Background polling 5 menit belum jalan satu siklus
• Hash compare detect “no change” karena admin re-write isi yang sama
• Realtime tidak available di self-hosted production (memang tidak ada push notification)

Fix:

• Pastikan tab SASE dibuka, status “Connected”
• Force RefreshConfigAsync manual via tombol (atau Disconnect → Connect)
• Verify config beda secara hash:

  curl "$SB/rest/v1/user_data?select=configuration" \
    -H "apikey:$ANON" -H "Authorization:Bearer $JWT" | jq -r '.[0].configuration' | sha256sum
  

• Kalau hash sama → admin populate ulang dengan content yang berbeda

11.15 Diagnostic checklist untuk support ticket

• OS + version
• Hermes Network 360 Guard version
• Helper Service version (HermesHelperSvc --version)
• Username Supabase
• Hostname endpoint
• wg show Hermes output
• Helper service status (Win: sc query / Mac: launchctl list)
• Tail 100 lines app.log (decrypted kalau ter-encrypt)
• Tail 50 lines Helper error log
• Steps to reproduce
• Screenshot

11.16 Eskalasi

Skenario	Eskalasi ke
WireGuard kernel module crash	wireguard-tools upstream
Helper Service bug	Internal repo HermesHelperSvc
Bug client SaseConnectionService / SaseConfigClient	Internal repo HermesNetwork360Guard
Schema user_data issue	DBA + ops
Gateway issue	Vendor SASE / ops Hermes
Bug Avalonia	github.com/AvaloniaUI/Avalonia

---

← Bab 10 Rencana Migrasi Bab 12 — FAQ →