Troubleshooting

Start with the doctor

/ecstacy doctor runs from the moment the plugin enables, even with the cloud link down. It is the first thing to run and the first thing support will ask for.

TEXT
/ecstacy doctor

Send the output verbatim. Summarising it removes the part that identifies the problem.

Symptom index

What you see Usually means Section
Failed to connect to cloud within timeout Outbound TCP is blocked Cannot connect
Players kicked on join, /ecstacy says it is still starting The plugin is not ready and is refusing to run unprotected Kicked on join
Console reports detection classes that failed to load The jar does not match what the cloud has for it Stale jar
Everything looks connected but nothing ever flags Exemption, a disabled check, or a genuinely clean server Nothing flags

Cannot connect to the cloud

Ecstacy dials out to cloud.ecstacy.ac:5001. Nothing needs to be opened inbound. The common cause is a host that blocks outbound TCP by default.

Test it from the machine running the server:

BASH
timeout 8 bash -c 'cat </dev/null >/dev/tcp/cloud.ecstacy.ac/5001' && echo reachable

If that fails, the fix is with your hosting provider: allow egress to cloud.ecstacy.ac on TCP port 5001.

If your firewall pins outbound source ports, or 49152 is already in use on the host, change the port the plugin binds locally:

settings.yml
cloud:
  local-port: 0    # 0 = let the OS pick a free ephemeral port

Note

cloud.local-port is the port the plugin opens on your machine, not the one it connects to. Changing it never fixes a blocked destination.

Players are kicked on join

If the plugin has not finished starting, it kicks joining players rather than letting them in unprotected. That is deliberate. A server that silently runs without detections is worse than one that is briefly closed.

It resolves itself once the connection and startup complete. If it does not, the underlying cause is one of the two sections above and below this one; run /ecstacy doctor.

If you would rather the plugin disable itself instead of holding the server closed:

settings.yml
cloud:
  disable-on-startup-connect-failure: true

Warning

With that set, a cloud outage means your server runs with no anticheat at all rather than rejecting joins. That is a policy choice, not a fix.

The console reports classes that failed to load

This almost always means the jar on disk is from an older build than the one the cloud has detections for.

Fix: download the jar again from the Client Area and replace the one in plugins/. Each build is matched to its own detections, so an out-of-date jar cannot use a current build's.

The plugin retries on its own a few times before giving up, so a one-off transient failure recovers without you doing anything. A failure that survives a restart and a fresh download is one to send to support with the /ecstacy doctor output.

Nothing is flagging

Work down this list in order:

  1. /ecstacy cloud: if it is not Connected, nothing will flag. Go back to Cannot connect.
  2. Check the exemption. ecstacy.exempt.* silences every detection for whoever holds it. It defaults to false for everyone including operators, so if it is set, someone set it. See Permissions.
  3. Check the family is enabled. /ecstacy checks, or enabled: true in checks.yml.
  4. Check the alerts are reaching you. /ecstacy alerts, and confirm you hold ecstacy.notify. A flag with no one listening looks identical to no flag.
  5. Check chat alerts are not switched off. alerts.mode: WEB_ONLY in settings.yml: or fail.alert.mode: WEB_ONLY on one check in checks.yml: suppresses the chat line on purpose. Detection is unaffected: open the dashboard or run /ecstacy logs. If flags are there and chat is empty, this is why. See Alert visibility.
  6. Look at the near-misses. /ecstacy suspicious lists players scoring just below the threshold. If that list is populated, detection is working and your precision is stricter than your player base.
  7. Check the near-miss queue instead of a live readout. The old ai.debug per-window readout was removed. /ecstacy suspicious is now the way to tell "nothing is happening" apart from "nothing is being scored": if it lists anyone, windows are reaching the model.

Tip

On a quiet server, "nothing flags" often means nothing is cheating. Before tuning precision down, confirm with /ecstacy suspicious that windows are being scored at all.

Still stuck

Bring three things to Discord:

  1. The full /ecstacy doctor output
  2. The relevant console lines, not a paraphrase
  3. Your server software and version, and whether the problem started after an update

The plugin also reports startup and connection failures back to the cloud automatically, so support can usually see the failure alongside your report.

Last updated