Troubleshooting#

packet-adapter: UNAVAILABLE in /ff status#

PacketEvents isn't installed, or failed to load before FlagForge (check console for its own startup lines). movement.timer.a/packet.rate.a/packet.sequence.a register but stay inert; every other check is unaffected. See Getting Started.

Persistence: DISABLED#

Check console for the Invalid storage.yml: or connection-failure line logged at startup. Detection still runs; nothing is stored, and no preventable action can execute (ActionDispatcher requires storage). See Configuration § storage.yml.

A check shows DISABLED (repeated internal errors) in /ff checks#

It threw 5 consecutive exceptions and was auto-disabled to protect the server. This is a bug — please report it with the SEVERE console line — then /ff reload or /ff check <id> enable to give it a fresh start once fixed.

Discord alerts never arrive but discord.enabled: true#

/ff discord status shows whether a webhook URL actually resolved. The default webhook-url value is an environment-variable reference (FLAGFORGE_DISCORD_WEBHOOK_URL) that never touches alerts.yml — but if you (or a previous administrator) opted into the literal-URL fallback instead, alerts.yml does then hold the raw secret in plaintext; check which form is currently configured before assuming it's unset. See Discord Staff Alerts for both setup paths.

A correlation rule isn't matching even though the individual findings look right#

Run /ff correlations — it shows every configured rule's thresholds live and flags any whose confidence requirement is currently unreachable given your checks.yml settings (most commonly: inventory.reconciliation.a's coverage-complete still false, or one side of a rule's required families having every contributing check experimental/disabled). See Tuning Guide § Evidence families and Configuration § actions.yml.

A CANCEL response never actually cancels anything#

Expected for every check except packet.payload.a right now — see Known Limitations § CANCEL is not yet live through the normal policy pipeline. Check ff_actions//ff status for a SUPPRESSED record with the reason, rather than assuming the finding was silently dropped.

Plugin doesn't load at all#

Check for Unsupported API version in console — this means you're running a Minecraft version older than 1.21.10; FlagForge cannot load at all there (this is Paper's own gate, not FlagForge's). A newer mismatched version loads but logs Version check: MISMATCH and registers zero gameplay listeners until you set operating-mode.unsupported-version-override: true for development. See Configuration § config.yml.

A staff member can't run any /ff subcommand#

Confirm they (or their permission group) have at least flagforge.command.status; individual subcommands need their own listed permission (see Staff Commands) even if the sender is an operator without a permissions plugin managing defaults correctly.