Connector Problems

Diagnose and fix issues with the AD Unlock connector.

Connector Won’t Start

Check Service Status


Get-Service ADConnector

Check Event Log


Get-EventLog -LogName Application -Source ADConnector -Newest 10

Common Causes

Cause	Solution
Config file not found	Verify `config.yaml` exists in installation directory
Invalid YAML syntax	Use a YAML validator to check config
Missing certificates	Check `certs/` folder has all required files
Port already in use	Check if another process is using required ports

Verify Config


# Check config syntax
cd C:\ADConnector
.\connector.exe --config config.yaml --validate

Connector Won’t Connect to Gateway

Check Network


Test-NetConnection -ComputerName api.adunlock.me -Port 443

Check DNS


Resolve-DnsName api.adunlock.me

Check Proxy

If using a proxy:


netsh winhttp show proxy

Configure proxy in environment:


$env:HTTPS_PROXY = "http://proxy.company.com:8080"

Check SSL Inspection


$webRequest = [Net.WebRequest]::Create("https://api.adunlock.me")
$webRequest.GetResponse() | Out-Null
$cert = $webRequest.ServicePoint.Certificate
Write-Host "Issuer: $($cert.Issuer)"
# Must be public CA, not internal

Connector Shows Offline in Portal

Check Heartbeat


Select-String -Path C:\ADConnector\logs\connector.log -Pattern "heartbeat" -Context 0,1 | Select-Object -Last 5

Check Connection


Select-String -Path C:\ADConnector\logs\connector.log -Pattern "connected|disconnected" -Context 0,1 | Select-Object -Last 10

Restart and Watch


Restart-Service ADConnector
Start-Sleep 5
Get-Content C:\ADConnector\logs\connector.log -Tail 20 -Wait

Jobs Not Being Processed

Check for Errors


Select-String -Path C:\ADConnector\logs\connector.log -Pattern "error|failed" | Select-Object -Last 20

Check AD Connectivity


Test-NetConnection -ComputerName dc01.company.local -Port 636

Test LDAP Bind


$cred = Get-Credential -UserName "svc_adunlock@company.local"
Get-ADUser -Identity svc_adunlock -Server dc01.company.local -Credential $cred

Certificate Issues

Check Certificate Validity


$cert = Get-PfxCertificate -FilePath "C:\ADConnector\certs\connector.pem"
Write-Host "Subject: $($cert.Subject)"
Write-Host "Expires: $($cert.NotAfter)"
Write-Host "Valid: $(if ($cert.NotAfter -gt (Get-Date)) { 'Yes' } else { 'No' })"

Renew Certificates

Admin Portal → Connectors → [Your Connector]
Click Renew Certificate
Download new bundle
Replace files in C:\ADConnector\certs\
Restart service

High Memory or CPU Usage

Check Resource Usage


Get-Process connector | Select-Object Name, CPU, WorkingSet64

Reduce Log Level

In config.yaml:


logging:
  level: "warn"  # Instead of "info" or "debug"

Increase Log Rotation


logging:
  max_size_mb: 5
  max_backups: 3

Collecting Diagnostic Information

When contacting support, collect:


# System info
Get-ComputerInfo | Select-Object CsName, OsName, OsVersion
 
# Service status
Get-Service ADConnector
 
# Recent logs (remove sensitive data before sharing)
Get-Content C:\ADConnector\logs\connector.log -Tail 100 > diagnostic-logs.txt
 
# Configuration (remove password)
Get-Content C:\ADConnector\config.yaml | Where-Object { $_ -notmatch "password" }
 
# Network tests
Test-NetConnection -ComputerName api.adunlock.me -Port 443
Test-NetConnection -ComputerName dc01.company.local -Port 636