FAQ & troubleshooting
Answers to common questions and quick fixes for the issues people hit most often.
I get certificate errors on HTTPS sites
The device or tool isn't trusting the BlankTrail Proxy root certificate. Install it from the dashboard's CA Certificate button, then restart the browser or tool. On Windows the installer usually does this for you; other devices need it installed manually.
“Port already in use”, or a 409 error
A refusal to open a port (POST /api/v1/ports/open) comes back as a 409 — except the debug capture port, which the handler itself refuses BEFORE the port manager, with a 403. There are many causes — read the response text, it names the cause outright. The frequent ones are below; only the first two are cured by changing the port number.
| Response text | What to do |
|---|---|
port N is already open | That number is already open IN THE APPLICATION itself. Take another one — or the one the dashboard suggests (GET /api/v1/ports/suggest does the same). |
port N is busy: listen tcp …: bind: … | The number is held by ANOTHER program: the listener never bound, and the tail after “bind:” is the operating system's own message. Take another number — or the one the dashboard suggests (GET /api/v1/ports/suggest). |
serving suspended: license inactive | The license is inactive: the subscription ended, or there has been no connection to the authorization server for a day. No port number will help — restore the connection or renew the subscription. |
port limit reached | The cap on simultaneously open ports for your plan is reached. Close the spare ports or move to a higher plan. |
the debug fingerprint port requires a Pro license | 🔴 The only row in this table that arrives with a 403 rather than a 409: the refusal is issued by the open-port handler, before the port manager. The debug capture port is available from the Pro plan. An ordinary port will open; a debug one will not. |
The list is not exhaustive: the same 409 carries other raw port-manager texts too — port N is already being opened (the same number is being opened right now), serving suspended during open: license inactive — port not started (the license lapsed mid-open), and the interception refusals: system interception is already taken by another port, this application is already intercepted by another port.
The port vanished on its own after I opened it
A port with no traffic closes ITSELF after 30 minutes — that is the shared idle timeout. The count starts when the port is opened, not at the last request: open a port, go away to set up your script, come back an hour later — and the port is gone, with nothing wrong with the application.
- A single port can be given its own: PUT /api/v1/port/{port}/idle with the body {"seconds": 0} never closes it, {"seconds": null} returns it to the shared timeout.
- The shared timeout changes with PUT /api/v1/idle_timeout and in config.yaml under portmanager.idle_timeout.
- 🔴 A call to ANY endpoint of that port counts as activity and resets the count. A monitor polling GET /status once a minute will keep the port open forever — while a scenario that opens a port in advance will lose it.
- For containers and servers there is a proper cure: the portmanager.startup_ports list in config.yaml. The product opens such ports itself and keeps them open, reopening them after the connection to the authorization server is restored.
My license does not activate
The obvious first: the email and password are those of the blanktrail.com account, the machine has internet access, and with two-factor confirmation enabled the ticket step must be completed.
The license is bound to a DEVICE, and it has a limited number of seats. Hence several distinct refusals, each with its own cure — the text reaches the dashboard, the tray tooltip and the response of GET /api/v1/license/status.
| Refusal text | What happened and what to do |
|---|---|
device limit reached | There are no seats left. Free a device in your account — usually an old machine, or a reinstalled system that counts as a new device. |
another copy of this device is running | A second copy of the same device is already running: a cloned virtual machine, say, or the product started twice. |
device key mismatch | The installation was re-identified elsewhere. Usually a state transfer between machines without the keys — activate again. |
device key required — reinstall the client | The device key is lost: the state file is damaged or deleted. Reinstall the client. |
device deactivated in your account | The device was deactivated in the account — turn it back on or free the seat. |
client build is below the minimum allowed | The build is too old. Update the client — how to do that is in the answer about updating. |
subscription expired | The subscription has ended: renew it in your account. |
no active license for this account | The account holds no active license — you signed in to the wrong account, or the license has not been bought yet. |
Still stuck? Contact support from your account and attach a report: the dashboard builds one itself (the bug report button), and it already carries the logs and the state of the ports.
The proxy returns 403 for some sites
If the dashboard header shows “Restricted to: …” under the plan name, you are on a service tariff: the port only routes to the listed domains and answers any other address with 403 Forbidden and an empty body (over SOCKS5: “connection not allowed by ruleset”; UDP ASSOCIATE is not granted at all). This is neither a broken proxy nor the upstream's fault — changing the egress will not help. The same list arrives as the allowed_domains field in the response of GET /api/v1/license/status. A bare entry covers the domain and all of its subdomains, an entry prefixed with “=” matches that exact name only, and a bare IP never matches. To reach other domains, change them in your account together with the tariff.
I forgot the dashboard password
The password is reset by re-activating the license: on the MACHINE ITSELF open /recover, sign in with the blanktrail.com account, and set a new dashboard password right there. There is no need to reinstall the product; the state is kept.
The API key is not governed by the dashboard password: it lives apart, and if that is what was lost, GET /api/v1/auth/apikey returns it and POST /api/v1/auth/apikey/rotate issues a new one.
A site demands a check — what now?
When a plain HTTP request is not enough and the site shows a challenge, Challenge Breaker takes over: it clears the check itself, returns the ready session to the same port, and the application carries on with ordinary requests. It is enabled per port in the Edit dialog and needs MITM. Available from the Pro plan; how many solver processes are busy is shown on the Overview tab.
How do I make sure a proxy isn't leaking?
Use the pre-flight leak check in the Open Port dialog, or the /upstream/test API with the "leak" check, before opening a port. It compares the DNS resolver against the exit IP and probes for an IPv6 escape route, so a leaky egress is caught up front.
Where do I find my API key?
Open the dashboard, click the gear icon to open Settings, and copy the API key shown there. You can rotate it in the same place if it may have been exposed. Send it as the X-API-Key header on API calls.
The proxy port asks for a login and password
If proxy-port authentication is enabled in the settings, the address in your application must carry the credentials — otherwise the connection is refused, and it looks like “the proxy does not work”.
# no authentication
curl -x socks5://127.0.0.1:20134 https://example.com
# with proxy-port authentication
curl -x socks5://proxyuser:[email protected]:20134 https://example.com- In the recommended Docker run command the proxy password is set BY DEFAULT — the container publishes its ports, and an open proxy with no password would be an open proxy for the whole network.
- The same caveat applies to the “accept connections from the local network” setting: turning it on hands the port to the neighbours, and the password stops being a formality.
- The login and password are set on the dashboard settings page, or with PUT /api/v1/settings/network through proxy_auth_enabled, proxy_auth_user and proxy_auth_pass. The check cannot be turned on without both.
How do I update?
The application FINDS an update by itself but does not install it: when a new version appears, the dashboard shows a “A new version is available” bar with a button. Until it is pressed, the previous version keeps running.
Once pressed, the update is downloaded, verified against its signature and swapped in, after which the application restarts itself. The license, the settings and the password are kept.
Two states where the button will not work, and neither is a fault. “Manual install needed” — the file cannot be swapped on this machine (the application sits somewhere unwritable, say); a download link appears next to it and the installer must be run by hand. “Update failed” — a “Try again” button stands next to it. Usually the attempt breaks BEFORE the file is swapped (download, signature check), and the previous version on disk is untouched. Less often the swap has already gone through and only the restart failed: by then the application has wound its work down and the NEW version is the one on disk, so starting it by hand brings up that new version. So when you see this state, restart the application and check the version: in the dashboard, or via GET /api/v1/update/status (the current field).
On Windows you can instead run the installer again and choose “Update — keep the license, settings and password”. On Linux updates arrive through the package service. To check the state from code: GET /api/v1/update/status; to start one: POST /api/v1/update.
How do I get help?
Sign in to your account at blanktrail.com and open support (Telegram or web chat). If you hit a bug in the app, the Settings dialog has a "Report a bug" option that sends a redacted diagnostic bundle to our team with your consent.