❓ FAQ

Three things happen, in order:

1. The plugin sees the HTTP error or timeout (your connectionTimeoutMs default is 3s).
2. If directFallbackEnabled: true, the plugin retries the lookup directly against an upstream provider. This sends the IP without the gateway's token, which is a privacy consideration. Default is false.
3. If that also fails (or is disabled), the plugin runs the lookup-failure policy. With blockOnLookupFailure: true (the default) the player is blocked with kickMessageLookupFailure. Flip it to false if you want fail-open.

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

The player's IP is sent to the Worker on every cache miss because the lookup provider needs the address to geolocate it. The Worker forwards it to the first provider that returns a valid result. GeoRestrict does not operate a central player dashboard or player analytics service.

For a gateway under your own account, deploy worker/src/index.js and set gatewayToken in the plugin config to match a token in the Worker's GATEWAY_TOKENS secret. Requests without a matching token receive HTTP 401.

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).

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 Hetzner VPS 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.

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.

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.

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.

Yes, on the Worker side. The gateway's provider endpoint settings accept arbitrary URLs with a {ip} placeholder. Whatever the endpoint returns is parsed by the same logic that parses the default upstream providers — if your provider returns a different shape, you'll need to fork the Worker.