§11 Troubleshooting
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.