# 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](active-directory.md#5-delegation--grant-per-feature).
- **"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`.