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.

Using SmarterMail? For problems with the SmarterMail connection, its SpamFoo settings, or what mailbox users see, go to Troubleshoot SmarterMail.

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.

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.

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 <process-id>"
sudo ss -ltnp | grep 16253

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.

In File Explorer, right-click the data directory, choose Properties > Security, and give the account Modify permission.

sudo chown -R <service-user>:<service-user> <data-dir>

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 <host-folder>

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. It names the setting. Correct it in the environment, the command line, or the 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. If it fails, start SpamFoo Client the same way you set it up in Install SpamFoo Client. If it won't stay running, see SpamFoo Client Won't 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.
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. 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 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.
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.

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. Then check the Updates log for download errors. See Read the 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.

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. 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.

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.
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.
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.
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 and How Corrections Are Used.

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.

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. See 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 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. 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.

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. For other ways to add it, and when you need to restart, see 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.

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.

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. Or paste the contents of etc/sf.proxysecret from the data directory. If you set SPAMFOO_PROXY_SECRET, use that value instead.

type "<data-dir>\etc\sf.proxysecret"
sudo cat <data-dir>/etc/sf.proxysecret
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.
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.
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.

The Page Won't Load

Cause
SpamFoo Client isn't running.
Fix
Run a 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.
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.

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.

Still Stuck?