Most people install CrowdSec, see green checkmarks, and assume they are safe. That assumption is exactly why you need a CrowdSec troubleshooting guide before you trust the tool with a real server, and this is the exact reason a proper CrowdSec troubleshooting matters more than a quick install checklist.

This CrowdSec troubleshooting guide covers the problems that actually show up in production:

• Logs that never reach a parser
• Decisions that never reach the bouncer
• Dashboards full of alerts with zero blocks
• False positives that lock out real users
• Community blocklist sync failures

What This CrowdSec Troubleshooting Guide Covers

A working CrowdSec setup has four moving parts, including log parsing, scenario detection, decision delivery to bouncers, and blocklist sync with the community network.

This CrowdSec troubleshooting guide checks each part on its own, so you can find exactly where things break instead of guessing. If you are running CrowdSec on a VPS to protect SSH, a website, or an API, this order of checks saves hours of confusion.

Step 1. Confirm CrowdSec Is Reading Your Logs

The first and most common failure in any CrowdSec troubleshooting guide is simple: CrowdSec is running, but it never sees your log lines. This happens when the acquisition file points to the wrong path, or the collection installed does not match your log format.

Check what CrowdSec is reading and parsing:

sudo cscli metrics show acquisition parsers

If your log file shows zero reads, open the acquisition config and confirm the path is correct:

sudo nano /etc/crowdsec/acquis.yaml

Make sure the filenames line points to the real log file and the labels.type matches an installed parser, like nginx, apache, sshd, syslog, etc.

After any change, restart the engine:

sudo systemctl restart crowdsec

If logs are being read but not parsed correctly, test a single log line directly:

sudo cscli explain --log "PASTE_YOUR_LOG_LINE_HERE" --type nginx

This command shows every parser stage your log line passed through, and exactly where it failed. A red mark means the parser rejected the line, usually because the log format does not match what the parser expects.

If you use a custom log format, you will need a custom parser, since the default nginx or apache parsers only understand the standard combined format.

Also, confirm the right collections are installed:

sudo cscli collections list
sudo cscli collections install crowdsecurity/nginx

Step 2. Fix Decisions Not Reaching the Bouncer

Once CrowdSec detects a threat, it creates a decision, but a decision does nothing until a bouncer applies it. This is the second failure point covered in this CrowdSec troubleshooting guide, and it is the reason dashboards can show alerts while attackers keep getting through.

Check if your bouncer is registered and pulling decisions:

sudo cscli bouncers list

Look at the “Last API pull” column. If it is empty or very old, the bouncer is not talking to the CrowdSec engine. Check the bouncer’s own log file for errors:

sudo tail -f /var/log/crowdsec-firewall-bouncer.log

Two errors show up the most. The first is a connection failure, which looks like this:

level=error msg="auth-api: auth with api key failed... connection refused"

This means the bouncer cannot reach the local API. Check the api_url value inside the bouncer config file, usually found in /etc/crowdsec/bouncers/, and confirm the CrowdSec engine is listening on that address and port.

The second common error is an authentication failure:

level=error msg="API error: access forbidden"

This means the API key is wrong or expired. Generate a new one and update the bouncer config:

sudo cscli bouncers add my-firewall-bouncer

Copy the new key into the bouncer configuration file, then restart the bouncer service.

Step 3. Prove Blocks Actually Happen

A dashboard full of signals means nothing if no traffic is actually being blocked. This step in the CrowdSec troubleshooting guide gives you a safe way to test remediation without waiting for a real attacker.

First, find your own public IP address:

curl api.ipify.org

Then add a short ban against that IP:

sudo cscli decisions add --ip YOUR_PUBLIC_IP --duration 1m --reason "remediation test"

Wait a few seconds, then try to load the protected website or service from that same IP. You should see a blocked page, a 403 response, or a captcha, depending on your bouncer type. If nothing happens, the decision exists, but the bouncer is not enforcing it, which points you back to Step 2.

After one minute, confirm the decision expired on its own:

sudo cscli decisions list

Be careful with this test, since it will briefly block your own access if you run it from the same device you use to manage the server.

Step 4. Fix False Positives Locking Out Real Users

False positives are common with brute-force and admin-panel scenarios, and fixing them is a core part of any CrowdSec troubleshooting guide, since they are one of the most frustrating parts of running CrowdSec on a public app. Instead of disabling the scenario completely, you can whitelist specific patterns.

To stop CrowdSec from ever banning certain IP ranges, such as your office or admin network, create a whitelist file:

sudo nano /etc/crowdsec/parsers/s01-parse/mywhitelist.yaml

Add the following content, adjusting the ranges to match your own network:

name: crowdsecurity/mywhitelists
description: "Whitelist trusted networks"
whitelist:
  reason: "trusted office IP range"
  ip:
    - "203.0.113.10"
  cidr:
    - "192.168.0.0/16"

If the false positive is tied to a specific URL pattern, like your login or admin page, whitelist the event instead of the whole IP:

name: crowdsecurity/admin_whitelist
description: "Whitelist admin panel path"
whitelist:
  reason: "false positive on admin login"
  expression:
    - "evt.Parsed.request startsWith '/admin'"

If a scenario keeps causing problems and you are not ready to fully remove it, put it in simulation mode. This keeps the alert visible in logs but stops it from creating a real block:

sudo cscli simulation enable crowdsecurity/http-bf
sudo systemctl reload crowdsec

For a full protection setup, see this guide on how to protect self-hosted apps with CrowdSec.

Step 5. Fix Community Blocklist Sync Problems

CrowdSec’s real value comes from the community blocklist, which shares malicious IPs seen across thousands of other servers. If this sync breaks, you lose most of the proactive protection, even if your local detection works fine.

Check the connection to CrowdSec’s Central API:

sudo cscli capi status

You should see a message confirming a successful connection. If this fails, the most common cause on a fresh install is missing credentials. Register the engine again:

sudo cscli capi register
sudo systemctl reload crowdsec

If registration still fails, check basic network access, since outbound connections must be allowed:

nslookup api.crowdsec.net
curl -I https://api.crowdsec.net

A firewall blocking outbound traffic, or a VPS behind strict egress rules, is often the real cause. If you use a proxy, add the proxy settings inside /etc/crowdsec/config.yaml so the engine can reach the API through it.

Keep in mind that the community blocklist only includes IPs tied to scenarios that are not tainted or customized. If you heavily modified a scenario like crowdsecurity/ssh-bf, you may see fewer shared IPs for that specific scenario, which is expected behavior and not a bug.

Why CrowdSec Needs the Real Visitor IP

If your app sits behind a reverse proxy such as Nginx or Traefik, CrowdSec needs to see the real visitor IP, not the proxy’s internal IP. Otherwise, every request looks like it comes from the same address, and bans either never trigger or accidentally block your entire proxy.

Make sure your reverse proxy passes the real client IP through headers, like X-Forwarded-For, and that your CrowdSec bouncer plugin is configured to trust that header only from your own proxy IP. Getting this wrong is a quiet failure that many people never notice until they check logs closely, which is exactly the kind of gap this CrowdSec troubleshooting guide is meant to catch.

If you are setting up a fresh server for this kind of stack, a reliable Linux VPS with enough resources for logs, a reverse proxy, and security tooling running side by side makes this whole process smoother.

Running CrowdSec on Windows Servers

CrowdSec also works on Windows, but Windows has its own services and firewall rules.

If you also manage exposed RDP or Windows-based services, pair this CrowdSec troubleshooting guide with a dedicated look at Windows VPS RDP security.

Conclusion

CrowdSec only works if every part does its job: parsing, detection, bouncer enforcement, and blocklist sync. Run through these steps in this guide after any new install, and again whenever your dashboard looks off.

We hope you enjoy this CrowdSec troubleshooting guide.

For more detailed information, check the Official CrowdSec Troubleshooting docs.

FAQs