Cannot connect or times out
Fix client login failures, connection refused and timed out errors, and bots that get kicked.
Identify the failed connection
First, identify which connection fails:
- your GUI or CLI cannot connect to the SoulFire server
- SoulFire is running, but the bots cannot stay connected to the target Minecraft server
Use the matching section below.
If the GUI or CLI cannot connect to the SoulFire server
Make sure that the server URL is correct
Make sure the client is using the actual server URL for the access mode you deployed:
https://your-domainorhttps://your-server-ipfor HTTPS frontends such as Traefik or Cloudflaredhttp://host:38765only when you intentionally deployed plain HTTP
Do not paste /docs, /mcp, or /webdav into the normal server login field.
Use a new access token
Generate a fresh token from the server side:
generate-token apiThen retry with that token. If an old token stops working, replace it with the new token.
Make sure that the deployment works
If this is a dedicated server:
- re-run the setup script management menu
- view the container health and logs
- make sure that the shown access URL matches the address in the client
If you deliberately chose HTTP-only mode, remember that some setups behave better behind HTTPS.
Test the client connection
An open documentation page does not prove that client login works. Test a normal GUI or CLI login with a new token.
If the bots connect to SoulFire but time out on the target Minecraft server
Remove proxies first
Disable proxies temporarily and test with one or two bots. If the timeouts disappear, the proxy pool is the problem, not the core session setup.
Reduce concurrency
Test with:
- fewer bots
- higher join delays
- one known-good account or offline mode where allowed
This test separates load problems from connection problems.
Review Bot Settings
Make sure that these values are correct:
- target server address
- protocol version
- connect/read/write timeout values
If local servers also fail, do not assume the remote target is the problem. This result points to a configuration error or SoulFire regression.
Review the server login requirements
Some target servers need:
- authenticated accounts instead of offline names
- specific protocol versions
- additional chat-based login or registration steps after joining
If the bot spawns and then disconnects, make sure that the session meets these requirements.
Read the project terminal
The project terminal is usually the fastest place to see whether the disconnect came from:
- a timeout
- a proxy connect failure
- authentication
- a plugin-driven action after join
If the Minecraft server kicks the bots
Read the first kick or disconnect message in the project terminal. Later messages often come from reconnect attempts.
| Message contains | Likely cause | Next check |
|---|---|---|
Connection refused | Wrong address or port, or the Minecraft server is not running | Join the same address with a normal client, then check the target address in Bot Settings |
timed out | The server, proxy, or network stopped responding | Test without proxies and with fewer bots |
Connection throttled | The server limits how fast one address can join | Increase the join delay |
Outdated client or Outdated server | The protocol version does not match the server | Set the protocol version and see Supported versions |
Failed to verify username | The server uses online mode, but the bot uses an offline account | Use a Microsoft account, see Accounts and authentication |
not white-listed | The server whitelist does not include the bot | Add the bot names to the whitelist on your test server |
| A register or login prompt | An authentication plugin such as AuthMe waits for chat input | Configure auto login and register |
| An AFK or idle message | The server kicks players that do not move | Enable the anti-afk built-in plugin |
The built-in auto-reconnect plugin is on by default.
It reconnects a kicked or timed-out bot after a short delay.
Repeated reconnects can trigger the server's join throttle, so turn the plugin off while you find the first kick reason.
If only some bots fail
That usually points to one of these:
- bad proxies
- bad accounts
- the target server rate-limiting or filtering connections
- different automation or script state between bots
Try the same test with:
- one bot
- no proxies
- one account
- no automation
If that works, add the layers back one at a time.
What to capture before you report it
- exact SoulFire version
- exact timeout or disconnect text
- whether
localhostalso fails - whether the issue happens with proxies disabled
- the smallest bot count that still reproduces it
Related pages
If the timeout started after an update, record the old and new SoulFire versions. This information helps developers reproduce a regression.
How is this page?
Last updated on
