Troubleshooting
Connection problems
Section titled “Connection problems””Cannot reach server”
Section titled “”Cannot reach server””Velauth cannot open a TCP connection to the domain controller.
Check:
- The hostname or FQDN you entered resolves from the machine running Velauth — open Command Prompt and run
nslookup corp.example.com. - Port 389 (LDAP) or 636 (LDAPS) is not blocked by a firewall between your PC and the DC.
- The DC is online. Try pinging it or connecting with another tool.
”Credentials rejected”
Section titled “”Credentials rejected””The bind credentials are wrong, or the service account is locked or disabled.
Check:
- Verify the username format:
DOMAIN\usernameor[email protected]. - Confirm the password is correct — test it by logging into Windows with those credentials.
- Check whether the service account is locked out using another AD tool or by asking a domain admin.
”SSL certificate error”
Section titled “”SSL certificate error””The DC’s LDAP certificate is not trusted by the machine running Velauth.
Fix:
- Import the domain’s root CA certificate into the Windows Trusted Root Certification Authorities store on the Velauth machine. Your AD administrator can export it from the CA.
- Alternatively, switch to unencrypted LDAP (port 389) if your environment permits.
Connection works in the wizard but breaks after restart
Section titled “Connection works in the wizard but breaks after restart”The stored credentials may have changed (password rotation) or the service account may have been locked.
Fix: Go to Settings → Domain connection, re-enter the password, and click Test & save.
Permission errors
Section titled “Permission errors””Access denied” when unlocking or resetting
Section titled “”Access denied” when unlocking or resetting”The AD service account does not have the delegated right for that operation on the target OU.
Fix: Ask a Domain Admin to delegate the following permissions on the relevant OUs to the Velauth service account:
| Operation | Required permission |
|---|---|
| Unlock | Write lockoutTime |
| Enable / Disable | Write userAccountControl |
| Reset password | Reset Password |
Use Active Directory Users and Computers → Delegate Control or the dsacls command-line tool.
”Role insufficient” error in the action panel
Section titled “”Role insufficient” error in the action panel”Your licence encodes the Auditor role, which has no write access.
Fix: Contact [email protected] to upgrade your licence to Operator or Administrator.
Audit log issues
Section titled “Audit log issues”Red “chain integrity” warning on the Audit page
Section titled “Red “chain integrity” warning on the Audit page”The audit hash chain has a gap — one or more entries may have been modified or deleted outside of Velauth.
Do not delete or modify audit files manually. Investigate whether %AppData%\Velauth\audit\ was modified by another process, and escalate to your security team if you cannot determine the cause.
Audit page loads slowly
Section titled “Audit page loads slowly”The audit log can grow large over time. Apply a date filter (e.g. last 30 days) to limit the rows loaded. Consider archiving old audit files from %AppData%\Velauth\audit\ to cold storage.
UI issues
Section titled “UI issues”The app opens but the user list is empty
Section titled “The app opens but the user list is empty”The domain connection may have failed silently after startup.
- Open Settings → Domain connection and click Test connection.
- If the test fails, fix the connection and return to the Users page.
- Press F5 to refresh the user list.
The app crashes on startup
Section titled “The app crashes on startup”Check the Windows Event Viewer under Windows Logs → Application for entries from Velauth. A Sentry crash report is sent automatically (if telemetry is enabled) — the crash ID is shown in the crash window before the app exits.
Contact [email protected] with the crash ID and the event log entry.
Collecting diagnostic information
Section titled “Collecting diagnostic information”If you need to send information to support:
- Open Settings → Support.
- Click Generate diagnostic bundle.
- Choose Save locally and attach the ZIP to your support email.
The bundle contains recent log files, system information, and the last 100 audit entries. No passwords, account names, or AD content are included.