Skip to content
SoulFire LogoSoulFire

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:

  1. your GUI or CLI cannot connect to the SoulFire server
  2. 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-domain or https://your-server-ip for HTTPS frontends such as Traefik or Cloudflared
  • http://host:38765 only 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 api

Then 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 containsLikely causeNext check
Connection refusedWrong address or port, or the Minecraft server is not runningJoin the same address with a normal client, then check the target address in Bot Settings
timed outThe server, proxy, or network stopped respondingTest without proxies and with fewer bots
Connection throttledThe server limits how fast one address can joinIncrease the join delay
Outdated client or Outdated serverThe protocol version does not match the serverSet the protocol version and see Supported versions
Failed to verify usernameThe server uses online mode, but the bot uses an offline accountUse a Microsoft account, see Accounts and authentication
not white-listedThe server whitelist does not include the botAdd the bot names to the whitelist on your test server
A register or login promptAn authentication plugin such as AuthMe waits for chat inputConfigure auto login and register
An AFK or idle messageThe server kicks players that do not moveEnable 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 localhost also fails
  • whether the issue happens with proxies disabled
  • the smallest bot count that still reproduces it

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