# The proxy could not reach one of its backend servers

A player tried to join through a Velocity, BungeeCord or Waterfall proxy, but the proxy could not connect to the backend server, so the player was turned away.

- Code: `proxy_backend_unreachable`
- Severity: error
- Category: Proxies
- Server types: Velocity, BungeeCord, Waterfall
- Page: https://failures.perland.online/failures/proxy_backend_unreachable/

## Example log

```text
[21:07:44 INFO]: [connected player] ExamplePlayer (/203.0.113.42:51876) has connected
[21:07:44 ERROR]: [connected player] ExamplePlayer (/203.0.113.42:51876): unable to connect to server survival
java.net.UnknownHostException: survival: Name or service not known
	at java.base/java.net.Inet6AddressImpl.lookupAllHostAddr(Native Method) ~[?:?]
	at java.base/java.net.InetAddress$PlatformResolver.lookupByName(Unknown Source) ~[?:?]
```

## Parameters

| Parameter | Meaning |
| --- | --- |
| `server` | The backend the player was sent to, by the name the proxy knows it under (Velocity names it). |
| `host` | The host name of the backend's address the proxy tried to connect to, when the log names it and it is not an IP address. |
| `reason` | Why the connection failed, when the log says it: `dns` (the name does not resolve), `connection_refused`, `timeout` or `unreachable` (no route on the network). |

## Log lines this page covers

- `unable to connect to server`
- `Error occurred processing connection for`
- `Could not connect to a default or fallback server. Incorrectly configured address/port/firewall?`
- `java.net.UnknownHostException`
- `Connection refused`
- `connection timed out`

## What it means

A proxy such as Velocity, BungeeCord or Waterfall is the one address players connect to. When a player joins, the proxy opens its own connection to a backend server (a lobby, a survival world) and passes the player through. Here that second connection failed: the proxy asked for the backend and got no answer it could use.

The proxy itself keeps running and other backends keep working. Only the player who tried to join (or switch servers) is turned away with a message that the proxy could not connect them. The issue only appears when someone joins, never at the proxy's start.

## Why it happens

The log usually says which of these it was:

- **The backend is not there (`dns`).** Its name does not resolve: the container or machine was stopped, removed or renamed, or the address in the proxy's config has a typo.
- **The backend refused the connection (`connection_refused`).** Something is at the address but nothing listens on the port yet. A Minecraft server refuses connections while it is still starting, so this is common right after a restart. A wrong port in the proxy's config gives the same result.
- **The backend did not answer in time (`timeout`).** It is frozen, overloaded or stuck on a long task, or a firewall drops the packets.
- **There is no route to it (`unreachable`).** The proxy and the backend are not on the same network, or a network between them is down.

## How to fix

1. Check that the backend is running and has finished starting: its log ends with a `Done (…)! For help, type "help"` line. If it is still starting, wait and join again.
2. If it stopped or crashed, read the backend's own log or diagnosis to see why, fix that, and start it.
3. If it runs but stays unreachable, compare the address the proxy uses with the backend's real one:
   - **Velocity:** the `[servers]` section of `velocity.toml`, such as `survival = "survival:25565"`.
   - **BungeeCord and Waterfall:** `address` under `servers` in `config.yml`.
4. For a timeout, look at the backend's console: a server that does not answer the proxy usually does not answer anything. Restart it if it is stuck.
5. **Docker:** the proxy and its backends must share a Docker network, and the proxy must use the service or container name and the port inside the container (25565), not the published host port.

## In Perland

Perland puts a network's proxy and backends on one internal Docker network and writes the proxy's server list itself, with each backend's address named after it. So this issue almost always means the backend was stopped, removed or still starting when the player joined; start the backend, or wait until it has started. Perland's diagnosis of the network's proxy reports the issue with the backend and the reason (through the API's network diagnosis and the `diagnose_server` tool for AI apps).

## References

- [Velocity configuration reference](https://docs.papermc.io/velocity/configuration)
- [BungeeCord configuration guide](https://www.spigotmc.org/wiki/bungeecord-configuration-guide/)