ADconsle/docs/troubleshooting.md

Troubleshooting

Turn on detail while diagnosing (dev/staging only):

APP_DEBUG=true
LOG_LEVEL=debug
LDAP_LOGGING=true

then php artisan optimize:clear and watch storage/logs/laravel.log.

---

I cannot log in

• "These credentials do not match our records" for a valid account — the account is not in AD_LOGIN_GROUP. Check the value is a correct DN or CN; nested membership and the primary group count. Empty AD_LOGIN_GROUP = nobody can log in.
• Every login fails, including known-good — the service account bind itself is failing (wrong LDAP_USERNAME/LDAP_PASSWORD, unreachable LDAP_HOSTS, or TLS handshake). See the LDAP lines in the log.
• "Can't contact LDAP server" — DNS/routing to LDAP_HOSTS, firewall on 636/389, or a TLS problem (below).

TLS / certificate errors

• LDAP_TLS_VERIFY=true but the DC cert chains to an internal CA the app host doesn't trust → install the root CA (/usr/local/share/ca-certificates/, update-ca-certificates) or set LDAP_TLS_VERIFY=false.
• Mixed settings: use either LDAP_SSL=true + port 636 or LDAP_TLS=true + port 389, not both.
• Verify from the host: openssl s_client -connect dc01.example.com:636.

The users / computers / groups list is empty

1. Base DN too narrow. LDAP_BASE_DN must be an ancestor of the users, computers and groups OUs. If they're siblings, use the domain root.
2. Default OU wrong. LDAP_DEFAULT_*_OU points somewhere with no objects — the tree opens there. Try the "whole domain" (globe) button in the module.
3. Stale cache after fixing .env — click the refresh/globe control, or php artisan optimize:clear, or wait out the 10-minute OU-tree TTL.
4. Config cache — you edited .env but didn't re-run php artisan config:cache.

Password reset fails

• Almost always no encrypted channel — set LDAP_SSL=true (or LDAP_TLS=true). AD refuses unicodePwd over clear LDAP.
• "insufficient access rights" — the service account lacks the Reset Password extended right on that OU. See active-directory.md.
• "constraint violation" — the new password violates the domain password policy (length/complexity/history). ADconsole only checks min:8 locally.

Enable/disable or unlock does nothing

Write permission on userAccountControl (enable/disable, "never expires") or lockoutTime (unlock) not delegated. The button returns without error but the DC rejects the write — check the log.

LAPS / BitLocker fields are blank

Those attributes are not world-readable. Grant the service account read on ms-Mcs-AdmPwd / msLAPS-Password (LAPS) and on the msFVE-RecoveryInformation child objects (BitLocker). Blank ≠ error — it means "not readable" or "not present on this computer".

GPO list is empty

The service account needs read on CN=Policies,CN=System,<baseDN>. Authenticated Users usually have it; a locked-down forest may not.

Dashboard numbers look wrong / stale

• The dashboard is cached 5 minutes. Hit Recalculate now.
• A yellow age badge = the cache is older than one refresh cycle; background recalculation isn't running (an LDAP error during rebuild — check the log).
• Counts stream every matching object with chunk(), so they are not capped; if a number seems low, verify the base DN and that the objects aren't filtered out (disabled users are still counted in totals).

500 error after deploy / upgrade

• php artisan migrate --force not run → missing panel_settings table.
• APP_KEY not set → php artisan key:generate.
• Stale cache → php artisan optimize:clear && php artisan optimize.
• storage/ / bootstrap/cache/ not writable by the web user.

php artisan test shows "DEPR" on every test

Expected. PHP 8.5 deprecates PDO::MYSQL_ATTR_SSL_CA, which PHPUnit references. Read the Tests: … summary line — deprecated there is not failed.