FAQ

Things people actually ask in support.

What if the Worker is down?

Three things matter:

  1. The plugin sees the HTTP error or timeout (your connectionTimeoutMs default is 3s).
  2. The plugin does not contact a geolocation provider directly. The configured Worker owns the lookup routes.
  3. If the Worker request still fails, the plugin runs the lookup failure policy. With blockOnLookupFailure: true (the default) the player is blocked with kickMessageLookupFailure. Set it to false if you want the join allowed during an outage.

Fresh cached entries continue to work during the outage because the cache is local to the server.

Where does the player data go?

The player's IP is sent to the configured Worker only when the plugin's local entry is missing or stale. It may then be processed by the services listed in the Privacy Policy. GeoRestrict does not operate a central player dashboard or player analytics service.

Can I block a specific ISP without blocking the country?

Yes. Set asnMode: BLOCKLIST and add the ASNs to asns. To find the ASN for a specific ISP, look up an IP from that ISP on a site like bgp.he.net — the AS number is right there in the result. Put it in as AS12345 (prefix optional).

My VPN detection keeps catching legit players. What do I do?

Look at the actual ISP names that are getting flagged. If you see something like "Hetzner Online GmbH" being blocked because a player happens to be on a hosted Hetzner server at home (rare, but it happens), trim vpnKeywords. The default list is conservative — it only flags well-known VPN/hosting providers — but the threshold depends on your player base.

You can also disable VPN detection entirely with vpnCheckEnabled: false.

Does this work with Velocity?

Yes, on Velocity 3.2.0 or later. The plugin uses the async login event continuation API. If you're on an older Velocity, upgrade — the API it needs was added in 3.2.0.

What about Folia?

Detected at startup. The plugin uses the global region scheduler for the config watcher and the async scheduler for everything else. There's nothing Folia-specific in the rule evaluator — it's just thread-safe maps and concurrent lookups.

Why does the cache file get rewritten so much?

It doesn't, usually. Writes are debounced to one every 5 seconds. A burst of cache writes coalesces into a single disk write. On shutdown, one final synchronous save happens.

If the file is changing more often than every five seconds during steady traffic, check whether another tool is touching config.yml and repeatedly triggering reloads, then compare the timestamps with the plugin log.

Can I use GeoRestrict for Geo-Routing without kicking players?

Yes! GeoRestrict includes a public Developer API (GeoRestrictAPI). Third-party plugins or custom proxy routers can call GeoRestrictAPI.getCountryCode(ip), GeoRestrictAPI.isVpn(ip), GeoRestrictAPI.getAsn(ip), or GeoRestrictAPI.lookup(ip) to perform raw geolocation queries and route players to nearby proxy servers without kicking them or evaluating restriction rules.

Can I use my own lookup provider?

Yes, but provider changes belong to the Worker, not the plugin config. Read the advanced infrastructure reference before changing that path.