Troubleshooting
Fix the most common VPNDetection problems by symptom: the wrong visitor address, missing fields, refused keys, rate limits and failed downloads.
On this page
- Every visitor has the same address
- A warning says a private address was looked up
- A field is missing from the answer
- cap_reached is true and the answer has fewer fields
- 401 Unauthorized
- 403 Forbidden on a lookup
- 402 Payment Required on /batch
- 429 Too Many Requests
- The middleware lets every request through
- The middleware never refuses anyone
- Lookups time out
- 403 with NOT_LICENSED when you download a database
- 503 when you download a database
- A VPN visitor isn't flagged
- Still stuck?
Find the symptom you see, then follow its fix. The most common problems come first.
Every visitor has the same address
Cause: Your app looks up the address of its own proxy, load balancer or CDN instead of the visitor's. If that address belongs to a hosting network, a rule that blocks hosting networks blocks everyone.
Fix: Tell your framework which proxies to trust, or read the address from your edge's own header, such as CF-Connecting-IP. See Client IP addresses.
Verify: Log the address your app passes to the lookup, and compare it with your public address at api.vpndetection.io/myip. They should match.
A warning says a private address was looked up
Cause: The address your app found is private, such as 10.0.0.5 or 127.0.0.1. On your own machine this is expected. Anywhere else, your app is reading its proxy's address.
Fix: On your own machine, no fix is needed: the framework packages answer private addresses locally, without a lookup. Elsewhere, fix the proxy setting as in the previous entry.
Verify: Deploy, make a request, and confirm that the warning no longer appears.
A field is missing from the answer
Cause: Your plan doesn't include the field. A missing field never means false; it means the field isn't in your plan.
Fix: Test whether a field is present before you read it, and treat a missing field as unknown. See Plans and fields.
Verify: Look up the same address with a paid key, or with a free account's key during its trial. The field should be present.
cap_reached is true and the answer has fewer fields
Cause: A paid key has used its organization's quota and overage is off, or overage is on and has reached the cap your organization set. The API answers with the free plan's fields instead of refusing the lookup.
Fix: Turn on overage, or raise the cap, in Billing in the console.
Verify: The next answer includes every field, and cap_reached is false.
401 Unauthorized
Cause: The key is unknown, revoked or expired.
Fix: Copy an active key from API > Keys in the console. To get the free plan's fields, you can also send no key at all.
Verify: The same request answers 200.
403 Forbidden on a lookup
Cause: The key lacks the ip.lookup scope, the key is limited to source addresses that don't include your server's, or the key was sent over plain HTTP.
Fix: In API > Keys in the console, add the IP lookup scope to the key, or add your server's address to its Allowed source addresses. If you sent the key over HTTP, rotate it, because anyone on the network path could have read it, and send the new key over HTTPS only.
Verify: The same request answers 200.
402 Payment Required on /batch
Cause: A batch of more than one address needs a paid plan.
Fix: Look up one address per request, or choose a paid plan.
Verify: The request answers 200 with results and errors.
429 Too Many Requests
Cause: Your requests exceeded a rate limit.
Fix: Wait for the number of seconds in the Retry-After header, then retry. The official libraries retry rate-limited requests for you.
Verify: The retried request answers 200.
The middleware lets every request through
Cause: The lookup fails, for example because of a network error or a refused key, and the framework packages fail open so that an outage of ours doesn't become yours.
Fix: Log the failure's reason, which the packages record with each request (for example req.vpndetection.error in Express), and fix the cause it names. To refuse requests when the lookup fails instead, set the package's fail-closed option.
Verify: Requests carry an answer and no error.
The middleware never refuses anyone
Cause: The middleware has no block condition, which is the default, or its condition names a field your plan doesn't include. A condition on a field your plan doesn't return can never match.
Fix: Add a block condition, using fields your plan includes, such as isVpn and isTor on the free plan. The middleware logs a warning once when a condition names a field your plan doesn't serve; check your logs for it.
Verify: A request through a VPN to a protected route answers 403.
Lookups time out
Cause: A lookup took longer than the timeout you set, because of a slow network path between your server and the API or a timeout that's too short for it.
Fix: Check the status page first. If the API is up, raise the timeout for that call, or cache answers so fewer requests wait on the network. On a request a visitor waits on, keep the timeout short and let the request through when it passes.
Verify: Lookups complete within the timeout, and your logs show no network errors.
403 with NOT_LICENSED when you download a database
Cause: Your organization holds no license for that database, or the license's term has ended.
Fix: Ask us for a license, or use one of the Open databases, which are free.
Verify: The download answers 302 and the file downloads.
503 when you download a database
Cause: You're licensed, but today's copy of the database hasn't been published yet.
Fix: Retry later.
Verify: The download answers 302.
A VPN visitor isn't flagged
Cause: Most often, your app looked up the wrong address (see the first entry). Less often, the address is new to our data.
Fix: Confirm that your app looks up the visitor's address. If it does, send us the address and what you know about it.
Verify: Look up the address directly, for example with curl https://api.vpndetection.io/ followed by the address, and compare the answer with what your app logged.
Still stuck?
Open Support in the console, or write to us through the contact form.