Source: https://help.spamfoo.com/guides/diagnostics Last updated: 2026-10-27 *** # Use Diagnostic Tools Use these tools to check that SpamFoo Client is running and to find out why it handled a message the way it did. For fixes to known problems, see [Fix Common Problems](https://help.spamfoo.com/guides/common-problems). Some steps below mention the **data directory**. This is the directory where SpamFoo Client keeps its database, logs, and keys. It is the install folder unless you start SpamFoo Client with `--data-dir=`. It is `/data` in Docker and `/var/lib/spamfoo` with the Linux package. The **Storage** card on **System > Status** in the admin console lists the exact folders. ## Check That SpamFoo Client Is Running The health check is the quickest test. Run it on the server where SpamFoo Client is installed. ### Windows ``` curl.exe http://localhost:16253/health ``` ### Linux ``` curl http://localhost:16253/health ``` ### Docker ``` curl http://localhost:16253/health docker ps --filter name=spamfoo-client ``` The image also runs this check on its own, so `docker ps` shows the container as healthy or unhealthy. If the command can't connect, SpamFoo Client isn't running. See [Read Startup Messages](https://help.spamfoo.com/guides/diagnostics#startup-messages) to find out why. A working service answers with `"status": "healthy"`. See [Check Queue Load](https://help.spamfoo.com/api/health#health) for what the other fields mean. ## Check That It Can Classify Mail A healthy answer means SpamFoo Client is running, not that it can classify mail. To check that, use the readiness check: ``` curl http://localhost:16253/health/ready ``` A `200` means it's ready, and a `503` lists the reasons. See [Check That It Is Ready](https://help.spamfoo.com/api/health#ready). With the Linux package or Docker, `spamfoo-client status` shows the same answer and also whether a license key is set up. See [Check Readiness](https://help.spamfoo.com/guides/commands#status). ## Read Startup Messages When SpamFoo Client starts, it prints messages that don't go into the log files. They show which folders it uses, whether it found a license key, and why it stopped if it fails to start. ### Windows Stop SpamFoo Client if it is running. Then start it in a Command Prompt from the install folder and read the output. Add the same options the service uses, such as `--data-dir=`. ``` cd spamfoo-client.exe ``` Press Ctrl+C to stop it when you are done. ### Linux ``` sudo journalctl -u spamfoo-client -n 100 ``` In standalone mode, which the Linux package uses, the journal also has every log line. ### Docker ``` docker logs spamfoo-client ``` Use your container's name in place of `spamfoo-client`. In standalone mode, the container's output also has every log line. Lines worth looking for: - `FATAL:`: a setting is wrong, and SpamFoo Client stopped. The line names the setting. See [It Stops With a Settings Error](https://help.spamfoo.com/guides/common-problems#config-error). - `Configuration file:`: the settings file SpamFoo Client read, and how many settings it applied. - `LicenseKey: Not Configured`: SpamFoo Client found no license key. - `ALERT: SpamFoo API not configured. Update checking disabled.`: models and the client won't update. - `Models directory:`: the folder where SpamFoo Client looks for its models. - `SpamFoo Dashboard static files not found`: the admin console files are missing. ## Check the Status Page In the admin console, go to **System > Status**. Check that the status line says **API connected**, the **License** card shows **Active**, and the **Versions** card lists a version for each model. An empty or old model version points to an update problem. For everything on the page, see [Check System Status](https://help.spamfoo.com/guides/admin-console#system-status). The **Mail Health** page also shows alerts at the top when SpamFoo Client can't reach the SpamFoo API or the license needs attention. ## Look Up a Message The **Messages** page shows how SpamFoo Client handled each scanned message. Use it when someone asks why a message was or wasn't marked as spam. 1. In the admin console, go to **Messages**. 2. Fill in one or more filters: **Sender Domain**, **Sender IP**, **Recipient**, **Detection Type**, or **Detection Path**. 3. Click **Search**. 4. Click a message to open its details. What to look at: - **Tag next to the result:** appears when something other than the machine learning model decided, such as **Admin block**, **Reputation block**, **Learned (spam)**, or **Phishing Model**. - **Verified:** whether the sender passed email authentication checks (SPF, DKIM, and DMARC, which confirm a message really came from the domain it claims). A message from a verified sender that was marked as spam deserves a closer look. - **Processing Steps:** in the message details, each step SpamFoo Client took, marked **Pass** or **Fail** where it applies. - **Message Content:** the stored subject and body, if **Store Message Content** is on. Right-click a message to create a rule for its sender or IP address, or to report a wrong result to SpamFoo. Messages are kept for the **Retention Period** set on **System > Settings**, which is 7 days by default. ## Read the Logs Start with the **Errors** log. It has every warning and error from all the other logs in one place. Read it on **System > Logs** in the admin console, or open the files in the `logs` folder of the data directory. See [Monitor Logs and Health](https://help.spamfoo.com/guides/monitoring) for each log and how to read it. To see the last 100 lines of today's Errors log: ### Windows In PowerShell: ``` Get-Content "\logs\errors-$(Get-Date -Format yyyyMMdd).txt" -Tail 100 ``` ### Linux ``` tail -n 100 /logs/errors-$(date +%Y%m%d).txt ``` ### Docker ``` docker exec spamfoo-client sh -c 'tail -n 100 /data/logs/errors-$(date +%Y%m%d).txt' ``` To log more while you look into a problem, set **Log Level** to **Detailed**, or turn on debug codes if support asks. See [Change How Much Is Logged](https://help.spamfoo.com/guides/monitoring#log-level).