> ## Documentation Index
> Fetch the complete documentation index at: https://bunny.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose unexpected Shield challenges and resolve false-positive rule triggers.

Unexpected Shield challenges and false-positive rule triggers usually trace back to one of a handful of features. This page covers how to find which one fired and how to resolve it.

## Why am I getting a Shield challenge?

Any Shield feature that supports the **Challenge** response action can issue one. If a challenge is appearing on requests you expected to pass, check each configured feature:

* **WAF**: [Custom WAF rules](https://bunny.net/docs/shield/custom-waf-rule.md) can add a Challenge action to matched request patterns.
* **DDoS Mitigation**: Higher [DDoS sensitivity levels](https://bunny.net/docs/shield/ddos.md) can present a Challenge to validate access to your site.
* **Rate Limiting**: [Rate limiting rules](https://bunny.net/docs/shield/custom-rate-limit-rule.md) can issue a Challenge once a client exceeds the configured threshold.
* **Bot Detection**: [Bot Detection](https://bunny.net/docs/shield/bot-detection.md) may issue a Challenge when traffic looks automated.
* **Access Lists**: Both [curated and custom Access Lists](https://bunny.net/docs/shield/access-lists.md) can be configured to present a Challenge.

Legitimate users should pass the challenge transparently. If challenges are firing repeatedly or on traffic that shouldn't be flagged, use the event logs to narrow down which feature is responsible.

## I have triggered a false positive

A false positive is a request that Shield logged or blocked when you would expect it to pass. To resolve one, find the rule in the event log, then apply an exception that fits.

### Inspect the event log

Event logs show exactly which rule matched and why. Logs are currently available via the API. See the [Shield event log endpoint](https://bunny.net/docs/api-reference/shield.md) for details.

The response includes a `TriggerMatch` field that identifies what the engine flagged. Example log:

```json theme={null}
{
  "logId": "c5c09fe1-2071-486c-b6ba-4c43b45aeb09",
  "timestamp": 1759913310543,
  "log": "{\"ServerZoneId\":4,\"Message\":\"Restricted File Access Attempt\",\"Url\":\"https://bunnyexample.test/.env\",\"RemoteIp\":\"1.2.3.*\",\"UrlEncodedBody\":null,\"Headers\":[{\"Name\":\"Accept\",\"Value\":\"*/*\"},{\"Name\":\"Host\",\"Value\":\"bunnyexample.txt\"},{\"Name\":\"User-Agent\",\"Value\":\"Python/3.10 aiohttp/3.12.15\"},{\"Name\":\"Accept-Encoding\",\"Value\":\"identity\"},{\"Name\":\"X-Forwarded-Proto\",\"Value\":\"https\"},{\"Name\":\"CDN-RequestId\",\"Value\":\"e139c9b1d59675e24a8a25fadf9c324b\"}],\"TriggerMatch\":{\"Key\":\"PMF\",\"Value\":\"/.env\"}}",
  "labels": {
    "asn": "48090",
    "country": "BG",
    "ruleId": "930130",
    "severity": "",
    "method": "GET",
    "ruleGroup": "",
    "status": "Blocked",
    "serverZone": "SG"
  }
}
```

In this case, `/.env` is matched as a common attack vector. The `ruleId` (`930130`) maps to the OWASP Core Rule Set entry for restricted file access, so this is a valid block.

More nuanced rules may need closer inspection. For example, PHP rules can trigger on open-ended PHP code (e.g., `<?php` without a closing `?>`). The `TriggerMatch` value will often contain a larger fragment of content you can use to confirm whether the match is genuine.

### Mitigate the trigger

Once you've identified the rule, there are three options, in order of preference:

1. **Add an exception inside the Shield feature that fired.** For example, allow a specific file, IP, or User-Agent within the WAF or Access List configuration.
2. **Add an Edge Rule exception.** [Edge Rules](https://bunny.net/docs/cdn/edge-rules.md) can disable parts (or all) of Shield based on conditions like a file extension, hostname, or URL path. Useful when the carve-out should apply only to specific traffic patterns.
3. **Disable the Shield rule entirely.** Only recommended as a last resort. Disabling a rule outright may expose your application to the attack vector that rule was protecting against.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.