Troubleshooting¶

Start with the checks below, then look up the symptom. FreeDR is pre-release; if a problem is not covered here, export diagnostics from the Health page and collect the service log before reporting it.

Known problems list

docs/KNOWN_PROBLEMS.md currently has no open end-user issues. Its open entries (KP-002 response verdict integrity, KP-003 Windows API read-only proof) are internal design limitations with no user-visible symptom or workaround.

Quick checks¶

1. Is the service running?¶

Item	Value
Service name	`FreeDR`
Display name	`FreeDR Endpoint Agent`
Start type	Automatic

Check it with any of:

Services (services.msc): FreeDR Endpoint Agent.
sc query FreeDR
freedrctl service status (asks for the FreeDR password; prints Running, Stopped, StartPending or StopPending).

freedrctl service start / stop need the FreeDR password and an elevated (administrator) prompt.

2. Is the API answering?¶

Open http://127.0.0.1:29173/ in a browser on the host.
Or run freedrctl status (add --port <n> if you changed the port). It prints the JSON from GET /status.

The API listens on loopback only (127.0.0.1), default port 29173 ([api] port in freedr.toml). It cannot be reached from another machine.

3. Check Health¶

Open Health in the console. The problems panel lists every item needing attention. See Health and status for what each component and counter means. Export diagnostics saves freedr-health.json (status, detection health and storage diagnostics).

4. Read the service log¶

File	Contents
`%ProgramData%\FreeDR\run\agent.log`	Service warnings and errors, one timestamped line each (`INFO`, `WARN`, `ERROR`).
`%ProgramData%\FreeDR\run\agent.log.1`	Previous log. The log rotates at 1 MiB, so at most about 2 MiB is kept.
`%ProgramData%\FreeDR\run\last-shutdown-spans.json`	Timings of the last service shutdown.

Other locations under %ProgramData%\FreeDR: freedr.toml (service configuration), config\evidence-lifecycle.json (retention), config\telemetry-filters.toml, data\evidence.duckdb (hot evidence), data\control.sqlite3 (alerts, cases, settings), data\cold\ (cold evidence files), password.json.

Do not widen folder permissions

The FreeDR folder is restricted to SYSTEM and Administrators. Opening it in Explorer and choosing Continue adds an access entry for your account. FreeDR removes such entries at the next service start and raises the alert FreeDR folder access list restored. Read files from an elevated command prompt instead.

Symptom	Cause	What to do
Browser shows `invalid request`	The address is not exactly `127.0.0.1:<port>` (for example `localhost`), or another site sent the request.	Use `http://127.0.0.1:29173/`.
Page does not load at all	Service stopped or still starting, or a different port is configured.	Check the service (above). `/ready` returns `starting` until the API component is up.
Incorrect password. Try again.	Wrong password.	Re-enter it. The password is the one set at installation (at least 12 characters).
Too many attempts. Wait a moment and try again.	More than 5 sign-in attempts in one minute.	Wait one minute.
Signed out unexpectedly	Sessions last 12 hours and end when the service restarts or the password changes. Only 16 sessions are kept; signing in more often drops the oldest.	Sign in again.
`freedrctl` prints `local API returned 401 Unauthorized`	Wrong password.	Retry; use `--password-stdin` for scripts (never pass the password as an argument).
`freedrctl` prints a connection error	Service not running or wrong `--port`.	Check the service and port.

Forgotten password¶

There is no password reset. No unauthenticated reset route or default password exists, and rerunning the installer does not reset it (it asks for the existing password when FreeDR data is present). Recovery is an administrator-managed reset of the installation; there is no supported way to bypass the password in normal use.

Installation¶

Symptom	Cause	What to do
Setup opens as Uninstall FreeDR	An installed service is never replaced.	Uninstall with the FreeDR password (tick Keep FreeDR data to keep it), then run setup again.
Setup asks for an existing password	FreeDR data from a previous install is present; it is kept.	Enter the previous password.
`FreeDR-Setup.exe /config` exits with code 3	Installed, but the configuration was not fully applied.	Enter AI, threat-intel keys and exclusions in Settings / Alert rules.
Exit code 2	Invalid input (for example a malformed key or configuration file). Nothing was installed.	Fix the file and rerun.
Exit code 1	Not installed.	Check the progress output and `agent.log`.
`freedrctl service install` fails	Not supported.	Install with `FreeDR-Setup.exe` or by running `freedr-agent.exe` (approve the UAC prompt).
Sysmon not installed on an offline machine	When Sysmon is absent, setup downloads it from Microsoft.	Install Sysmon before installing FreeDR on offline hosts. An existing Sysmon is left unchanged.

Health shows degraded¶

Symptom	Cause	What to do
A component stays degraded although the problem is gone	Degraded is held for 30 minutes after the last fault (ADR-0080).	Wait. Check `degraded_last_fault_unix_s` and `degraded_episodes` on the component to see when and how often it happened.
Counters such as `events_lost` or `acquisition_errors` are non-zero but the component is healthy	Counters are lifetime totals since agent start; only current faults degrade.	No action unless they keep growing. The Health page shows the change since your last refresh for artifact loss counters.
Windows Event Log degraded; tray says Event Log channel closed	A configured Event Log channel stopped delivering events (or committing events is failing). Channels not present on this host do not count.	Check Settings > Sources for the channel and Sysmon status; check `agent.log`. Evidence from that channel may be missing.
Telemetry sources degraded (`changes_outcome_unknown`)	A change from Settings > Sources has no recorded outcome because the service stopped during it.	Open Settings > Sources, check those sources and reapply or restore as needed.
Provider settings degraded (`settings_reset_invalid`)	Stored enrichment/AI settings were invalid or from an older version and were reset to defaults.	Re-enter provider settings and keys in Settings > Enrichment & AI.
Cold storage export degraded	A move of hot evidence to cold files failed.	Check `agent.log` and free disk space (Health > Storage).
Evidence database writer degraded	Writes were rejected, invalid or failed, or the queue was full.	Check `agent.log` and free disk space.
Detection engine degraded	Rule startup or evaluation error, or a control-database problem (`sqlite busy or locked`, `sqlite integrity check failed`).	Read the reason on Health or Alert rules. SQLite busy/persistence errors clear after a later successful write.
Storage integrity item in the problems panel	The control database integrity check reported foreign-key violations or messages.	Export diagnostics and keep `agent.log`; do not edit the database files.

Alerts and notifications¶

Symptom	Cause	What to do
No Windows notifications for new alerts	Notifications are off by default; minimum severity defaults to High. Informational alerts never notify; muted rules do not notify.	Enable in Settings > Notifications and choose a minimum severity.
Notifications enabled but nothing appears	No tray in the console session: nobody signed in at the console (for example RDP only or signed out), or the tray was closed with Exit. Counted in the `tray` counter `notices_without_tray`.	Sign in at the console. After Exit, the tray returns when the console session changes or you sign in again.
Protection degraded tray icon	A component is degraded.	Open Health.
Alert FreeDR service was stopped	The service was stopped on request (administrator, uninstall or upgrade); recorded at the next start. No telemetry was collected while stopped.	Expected after a deliberate stop; investigate otherwise.
Alert FreeDR folder access list restored	Extra access entries were found on FreeDR folders at start (for example after Explorer Continue) and removed.	Check recent changes to those folders, as the alert text says.
Alert appears after turning a source off in Settings > Sources	Turning a source off is reported as an alert by design.	Expected when you made the change.
Too many alerts from one rule	Benign activity matches the rule.	Use False positive / mute… on the alert to add a user exception or mute the rule for 24 hours or 7 days.

Tray icons and notices are implemented but still pending native Windows qualification (ADR-0067).

Queries and storage¶

Symptom	Cause	What to do
`evidence reader busy`	The API runs a limited number of evidence reads at once (two reads, one export).	Wait for running queries or exports to finish, then retry.
Old evidence is gone	Cold files older than the Retention period (default 90 days) are deleted during cold export.	Raise the retention period in Settings > Storage if you need more history. Expired evidence cannot be recovered.
Want to change how long evidence stays "hot"	Hot retention (default 45 minutes) is a service setting.	Not available in Settings; it is shown read-only.
Statistics could not be counted completely or incomplete results	The query did not complete.	Narrow the time range or filter and run again.