Source: https://help.spamfoo.com/guides/common-problems Last updated: 2026-10-27 *** # Fix Common Problems This page lists common problems with SpamFoo Client, what causes them, and how to fix each one. To dig deeper into a problem, see [Use Diagnostic Tools](https://help.spamfoo.com/guides/diagnostics). > **Using SmarterMail?** For problems with the SmarterMail connection, its SpamFoo settings, or what mailbox users see, go to [Troubleshoot SmarterMail](https://help.spamfoo.com/integrations/smartermail/troubleshoot). Many fixes below mention the **data directory**. This is the directory where SpamFoo Client keeps its database, logs, models, and the `etc` folder with its keys. It is the install folder unless you start SpamFoo Client with `--data-dir=`. In Docker it is `/data`, and with the Linux package it is `/var/lib/spamfoo`. To see the exact folders, open the admin console and go to **System > Status**. The **Storage** card lists each location. ## SpamFoo Client Won't Start If you can't tell why SpamFoo Client stopped, read its startup messages first. See [Read Startup Messages](https://help.spamfoo.com/guides/diagnostics#startup-messages). ### It Stops Right After It Starts **Cause:** Another program is already using port 16253. SpamFoo Client always listens on this port, so only one copy can run on a server. **Fix:** Find the program that is using the port and stop it. If it is another copy of SpamFoo Client, keep only one running. #### Windows In a Command Prompt, find the process ID (the last number on the line), then look up its name: ``` netstat -ano | findstr :16253 tasklist /fi "pid eq " ``` #### Linux ``` sudo ss -ltnp | grep 16253 ``` #### Docker Check for another container that publishes port 16253, then check the host as shown on the Linux tab. ``` docker ps --filter publish=16253 ``` **Cause:** The account that runs SpamFoo Client can't write to the data directory. SpamFoo Client creates its log folder, database, and keys there when it starts. **Fix:** Give that account permission to create and change files in the data directory. #### Windows In File Explorer, right-click the data directory, choose **Properties > Security**, and give the account **Modify** permission. #### Linux ``` sudo chown -R : ``` #### Docker The container runs as user ID 10001. A named volume sets this up for you. If you mount a host folder instead, give it to that user: ``` sudo chown -R 10001:10001 ``` ### It Stops With a Settings Error **Cause:** A startup setting has a value SpamFoo Client can't use, such as a `SPAMFOO_MODE` other than `embedded` or `standalone`, a `SPAMFOO_PORT` that isn't a port number, a `SPAMFOO_PUBLIC_URL` that doesn't start with `http://` or `https://`, or a `--conf` file that doesn't exist. SpamFoo Client prints a line that starts with `FATAL` and stops with exit code 78. The Linux package's service doesn't restart after this exit code, so it stays stopped. **Fix:** Read the `FATAL` line in the [startup messages](https://help.spamfoo.com/guides/diagnostics#startup-messages). It names the setting. Correct it in the environment, the command line, or the [settings file](https://help.spamfoo.com/guides/configure#settings-file), then start SpamFoo Client again. ## Mail Isn't Being Classified ### Messages Get No Result **Cause:** SpamFoo Client isn't running. **Fix:** Run a [health check](https://help.spamfoo.com/guides/diagnostics#health-check). If it fails, start SpamFoo Client the same way you set it up in [Install SpamFoo Client](https://help.spamfoo.com/guides/install). If it won't stay running, see [SpamFoo Client Won't Start](https://help.spamfoo.com/guides/common-problems#wont-start). **Cause:** Your mail server never sends messages to SpamFoo Client. If no new messages show up on the **Messages** page in the admin console, mail isn't reaching it. **Fix:** Check that your integration sends each message to `http://localhost:16253/classify-stream`, or to the server's address if the mail server runs on another computer. See [How Integration Works](https://help.spamfoo.com/integrations). **Cause:** The mail server runs on a different computer. By default, SpamFoo Client only accepts connections from the computer it runs on. **Fix:** Set the `SPAMFOO_BIND_ADDRESS` environment variable to an address the mail server can reach, then restart SpamFoo Client. See [Configure SpamFoo Client](https://help.spamfoo.com/guides/configure). The Docker image already listens on all addresses. **Cause:** Requests don't include the proxy secret. SpamFoo Client answers them with a 401 error and `{"error":"unauthorized"}`. See [Mode](https://help.spamfoo.com/guides/configure#mode) for which requests need it. **Fix:** Have the mail server send the proxy secret in the `X-SpamFoo-Proxy-Auth` header. The secret is the contents of `etc/sf.proxysecret` in the data directory, or the value of `SPAMFOO_PROXY_SECRET` if you set it. See [API Overview](https://help.spamfoo.com/api). **Cause:** The proxy secret changed, and the mail server still sends the old one. In standalone mode, the old secret keeps working for 15 minutes after the change, then requests get a 401 error. **Fix:** Give the mail server the new secret. See [Change the Secret](https://help.spamfoo.com/guides/roles#change-the-secret). ### Requests Wait a Long Time, Then Fail **Cause:** SpamFoo Client hasn't downloaded its models yet. It downloads them the first time it starts. Until they are ready, classification requests wait, and they fail if the models don't arrive within about 10 minutes. The download needs a license key and a connection to the SpamFoo API. **Fix:** Run `curl http://localhost:16253/health/ready` on the server. While the models are missing, the answer lists `models_loading`, and `not_activated` means there is no license key. Open the admin console. If **Mail Health** shows "No license set up" or "API disconnected", follow the steps in [Updates Fail](https://help.spamfoo.com/guides/common-problems#updates-fail). Then check the **Updates** log for download errors. See [Read the Logs](https://help.spamfoo.com/guides/diagnostics#logs). ### Requests Fail With a 403 Error **Cause:** Your license doesn't include the feature the request needs. The response contains `"error":"feature_not_licensed"` and names the features. **Fix:** Go to **System > Status** and check the **License** card to see which features your plan includes. To add a feature, change your plan in your SpamFoo account. **Cause:** The license has expired. **Fix:** Follow the steps in [Requests Fail After the License Expires](https://help.spamfoo.com/guides/common-problems#license-expired). ### Requests Fail After the License Expires **Cause:** SpamFoo Client stops classifying mail when its license has expired and the grace period has ended. Every classification request gets a 403 error with `"error":"feature_not_licensed"`. The **License** card on **System > Status** shows **License expired**. In embedded mode, SpamFoo Client keeps classifying. **Fix:** Renew the license in your SpamFoo account. If you got a new license key, add it with [`spamfoo-client activate`](https://help.spamfoo.com/guides/commands#activate). SpamFoo Client starts classifying again once it confirms the license, with no restart. **Cause:** SpamFoo Client couldn't reach SpamFoo to confirm the license. **Fix:** Allow the server to make outbound HTTPS connections (port 443) to `global-api.spamfoo.com`. SpamFoo Client checks the license again every few hours. To check right away, restart SpamFoo Client. ### Requests Fail With a 429 Error **Cause:** An IP address sent a wrong proxy secret or a bad sign-in link too many times in a short period. SpamFoo Client blocks every request from that address for some time. The response contains `"code":"auth_blocked"` and a `Retry-After` header with the seconds left. **Fix:** Find the program sending the wrong secret, often a mail server or script that still has an old one, and give it the current secret. Then wait for the block to end, or restart SpamFoo Client to clear it. If a reverse proxy runs on the same server, every request through it shares one address, so one bad client can block everyone behind the proxy. ## Too Much or Too Little Spam Start by finding the message on the **Messages** page in the admin console. When a rule, sender reputation, Anti-Phishing, or a mailbox's past corrections decided the result, a tag next to the result says so, such as **Admin block** or **Learned (spam)**. With no tag, the machine learning model decided. Click the message to see more detail. See [Look Up a Message](https://help.spamfoo.com/guides/diagnostics#messages). ### Good Mail Is Marked as Spam **Cause:** A Spam Rule marks the sender as Spam. The tag reads **Admin block** or **User rule (spam)**. **Fix:** Go to **Rules** and change or delete the rule. Users manage their own rules on **My Rules**. See [Manage Spam Rules and Senders](https://help.spamfoo.com/guides/rules-protection). **Cause:** The sender has a poor reputation. The tag reads **Reputation block**. **Fix:** On the **Messages** page, right-click the message and choose **Create rule**. Set **Action** to **Not Spam**. **Cause:** Anti-Phishing flagged the message. The tag reads **Phishing Model**, **Impersonation**, **Look-alike domain**, or **Typosquat domain**. A typosquat domain is a domain spelled almost like a well-known one. **Fix:** If the tag reads **Phishing Model**, go to **Anti-Phishing > Detection** and set **Sensitivity** to **Conservative**. For any of these tags, you can add a Spam Rule with the action **Not Spam** for a sender you trust. See [Protect Against Phishing](https://help.spamfoo.com/guides/phishing-protection). **Cause:** The mailbox's past corrections decided the result. The tag reads **Learned (spam)**. **Fix:** Have the user mark the message as Not Spam. See [Correct a Wrong Result](https://help.spamfoo.com/guides/correct-result). **Cause:** The machine learning model got it wrong. **Fix:** Right-click the message and choose **Report Misclassification**, or have the user mark it as Not Spam. See [Correct a Wrong Result](https://help.spamfoo.com/guides/correct-result) and [How Corrections Are Used](https://help.spamfoo.com/guides/corrections). ### Spam Gets Through **Cause:** A Spam Rule allows the sender. The tag reads **Admin allow** or **User rule (allow)**. **Fix:** Go to **Rules** and change or delete the rule. **Cause:** The mailbox's past corrections let the message through. The tag reads **Learned (allow)**. **Fix:** Have the user mark the message as Spam. **Cause:** The machine learning model missed it. **Fix:** Right-click the message and choose **Report Misclassification**, or have the user mark it as Spam. To block a sender right away, right-click the message and choose **Create rule** or **Create rule for IP**. **Cause:** The models are out of date because SpamFoo Client can't download updates. **Fix:** Go to **System > Status** and check the **Versions** card and the status line at the top. If it says "API disconnected", see [Updates Fail](https://help.spamfoo.com/guides/common-problems#updates-fail). ## Slow Responses ### Messages Take a Long Time to Scan **Cause:** Mail arrives faster than SpamFoo Client can scan it. The **Scan Queue** tile on **System > Status** shows messages waiting. **Fix:** Check the **CPU** tile on the same page. If the CPU has room to spare, go to **System > Settings** and raise **Max Concurrency** in the **Classification** card. This sets how many messages SpamFoo Client scans at the same time. If the CPU is already busy, give the server more resources or [turn on GPU acceleration](https://help.spamfoo.com/guides/gpu-acceleration). See [System Requirements](https://help.spamfoo.com/guides/system-requirements). **Cause:** **Enable Speedup Optimizations** is on while several messages are scanned at once. This setting lets a single scan use every CPU core, so scans running together compete for the same cores. **Fix:** Go to **System > Settings**. In the **Classification** card, lower **Max Concurrency** or turn off **Enable Speedup Optimizations**. **Cause:** SpamFoo Client just started or is loading new models. It loads its models when the first message arrives, and it pauses scanning briefly while it switches to updated models. **Fix:** Wait a few moments. A [health check](https://help.spamfoo.com/api/health#health) shows `"modelReloading": true` while new models load. ### Requests Fail With a 503 Error **Cause:** A message waited in the scan queue longer than the **Queue Timeout** setting. The response contains `"error":"Classification queue timeout"`. **Fix:** Follow the steps in [Messages Take a Long Time to Scan](https://help.spamfoo.com/guides/common-problems#slow-scans). You can also raise **Queue Timeout** in the **Classification** card on **System > Settings**. A value of 0 means messages wait as long as needed. ## Updates Fail When updates fail, SpamFoo Client keeps classifying mail with the models it already has. Details about each update check are in the **Updates** log. See [Read the Logs](https://help.spamfoo.com/guides/diagnostics#logs). ### Models and the Client Don't Update **Cause:** No license key is set up. **Mail Health** shows **No license set up**. Without a key, SpamFoo Client doesn't check for updates at all. **Fix:** Add the key with [`spamfoo-client activate`](https://help.spamfoo.com/guides/commands#activate). For other ways to add it, and when you need to restart, see [License Key](https://help.spamfoo.com/guides/configure#license-key). **Cause:** SpamFoo Client is using a different data directory than you expect, so it doesn't find your key file. **Fix:** The **License key** row in the **Storage** card on **System > Status** shows exactly where SpamFoo Client looks for the key file. Put the key there, or start SpamFoo Client with the data directory you meant to use. If you start SpamFoo Client with a custom data directory, write the option with an equals sign, such as `--data-dir=/var/spamfoo`. A space instead of the equals sign is ignored. **Cause:** Your license is past due, suspended, expired, or canceled. **Mail Health** shows an alert with the license status. **Fix:** Bring the license back to good standing in your SpamFoo account. **Cause:** SpamFoo Client can't reach the SpamFoo API. **Mail Health** and **System > Status** show **API disconnected**. **Fix:** Allow the server to make outbound HTTPS connections (port 443) to `global-api.spamfoo.com`. To check for updates right away, go to **System > Status** and click **Run** next to **Update Models** in the **Maintenance** card. ### A Client Update Keeps Failing **Cause:** The update can't replace the files in the install folder, usually because of disk space or permissions. After three failed tries on the same version, SpamFoo Client stops trying that version until a newer one is released. **Fix:** Read `updates/update.log` in the install folder to find the error. Make sure the account that runs SpamFoo Client can change files in the install folder and that the disk has free space. **Cause:** You run SpamFoo Client in Docker. The container never replaces its own program. **Update Client** only shows whether a newer version is available. Models still update on their own. **Fix:** Pull a newer image tag and recreate the container with the same `/data` volume. See [Update and Back Up](https://help.spamfoo.com/guides/updates). ### SpamFoo Client Stops After an Update **Cause:** To install a new version, SpamFoo Client closes and expects the program that manages it to start it again. A Linux service set to `Restart=on-failure` may not restart it. **Fix:** Set the service to restart whenever SpamFoo Client stops. On Linux, change the `[Service]` section of the unit file, then reload it: ``` Restart=always ``` ``` sudo systemctl daemon-reload sudo systemctl restart spamfoo-client ``` ## Database Grows Too Large The **Storage** card on **System > Status** shows the database size, how many messages are stored, and the date of the oldest record. Settings named below are on **System > Settings**. Click **Save Changes** after you change them. ### The Data Directory Uses Too Much Disk Space **Cause:** Scan history, stored messages, nightly backups, or log files have grown. **Fix:** Check the **Storage** card on **System > Status**, then lower the matching settings. See [Disk Space](https://help.spamfoo.com/guides/system-requirements#disk-space). ## Can't Open the Admin Console ### The Console Asks for a Proxy Secret **Cause:** The admin console is protected by a proxy secret. In standalone mode, SpamFoo Client shows a "Sign in to SpamFoo" page until you enter it. **Fix:** Make a one-time sign-in link on the server with [`spamfoo-client login-link`](https://help.spamfoo.com/guides/commands#login-link). Or paste the contents of `etc/sf.proxysecret` from the data directory. If you set `SPAMFOO_PROXY_SECRET`, use that value instead. #### Windows ``` type "\etc\sf.proxysecret" ``` #### Linux ``` sudo cat /etc/sf.proxysecret ``` #### Docker ``` docker exec spamfoo-client cat /data/etc/sf.proxysecret ``` **Cause:** The console shows "That secret did not work." The value you pasted is incomplete, or the secret was changed. **Fix:** Copy the whole value again, using the steps above. **Cause:** The console shows "Saved secret no longer works." An older version of SpamFoo Client saved the secret in your browser, and the secret changed since. **Fix:** Paste the current secret, using the steps above. **Cause:** You were signed in, and now the sign-in page appears again. The proxy secret changed, which signs everyone out, or your sign-in expired after 24 hours. **Fix:** Sign in again with the current secret or a new sign-in link. **Cause:** SmarterMail manages this SpamFoo Client. SmarterMail signs you in, so there is no secret for you to enter. **Fix:** Open the SpamFoo dashboard from SmarterMail. See [Troubleshoot SmarterMail](https://help.spamfoo.com/integrations/smartermail/troubleshoot). ### A Sign-In Link Can't Be Used **Cause:** The page says "This sign-in link cannot be used." The link expired, was already used, or stopped working because the proxy secret changed. **Fix:** Make a new link with `spamfoo-client login-link`. To make a link that lasts longer, add `--minutes=`. See [Make a Sign-In Link](https://help.spamfoo.com/guides/commands#login-link). **Cause:** The link points to `localhost`, so it only opens on the server itself. **Fix:** Make the link with `--url=` set to the address you use to reach SpamFoo Client, or set [`SPAMFOO_PUBLIC_URL`](https://help.spamfoo.com/guides/configure#public-url). ### The Page Won't Load **Cause:** SpamFoo Client isn't running. **Fix:** Run a [health check](https://help.spamfoo.com/guides/diagnostics#health-check) and start SpamFoo Client if needed. **Cause:** You are browsing from another computer. By default, SpamFoo Client only accepts connections from the computer it runs on. **Fix:** Open `http://localhost:16253/admin` on the server itself. To reach the console from other computers, see [Use the Admin Console](https://help.spamfoo.com/guides/admin-console). **Cause:** The console files are missing from the install folder. The startup messages include "SpamFoo Dashboard static files not found." **Fix:** Back up the data directory, then reinstall SpamFoo Client from a fresh download. See [Install SpamFoo Client](https://help.spamfoo.com/guides/install). ### Some Pages Are Missing **Cause:** You are signed in as a Domain Admin or User. Only a System Admin sees server-wide pages such as **Mail Health**, **Messages**, **Senders**, and **System**. **Fix:** Sign in with a System Admin account. See [Manage Sign-In and Roles](https://help.spamfoo.com/guides/roles). ## Still Stuck? - Use the tools in [Use Diagnostic Tools](https://help.spamfoo.com/guides/diagnostics) to find the cause. - Check the **Errors** log for warnings and errors. See [Monitor Logs and Health](https://help.spamfoo.com/guides/monitoring).