Fix Minecraft server connection problems

Use the error message and server state to identify whether the problem is the address, edition, version, port, whitelist, server process, network, or recent configuration.

Published by PortalMine Operations & Documentation TeamReviewed July 13, 2026Reading time: 8–12 minutes

Start with the exact error

“It does not work” can describe many different failures. Copy the exact message and note whether the problem affects one player or everyone. Also record whether the dashboard says installing, offline, starting, online, stopping, or error.

Error or symptomLikely areaFirst checks
Connection refusedServer offline, wrong port, process not listeningConfirm online state and exact connection details.
Connection timed outRouting, firewall, wrong address, overloaded or unreachable serverTest another network and confirm status/logs.
Unknown hostHostname typo or DNS problemPaste the address again without spaces or web prefixes.
Outdated client/serverVersion mismatchMatch the client and server version.
Not whitelistedAccess controlAdd the correct player name or disable whitelist intentionally.
Authentication/session errorClient login or online-mode authenticationRestart the client and use a valid authenticated session.

Universal checklist

  1. Verify the server is online

    “Created” does not always mean “ready.” Wait for installation and startup to complete.

  2. Confirm edition

    Java clients cannot normally join a Bedrock/Nukkit server, and Bedrock clients cannot normally join a Java server.

  3. Copy the address again

    Do not include https://, trailing punctuation, or spaces.

  4. Check the Bedrock port

    Use the exact port from the dashboard rather than assuming a default.

  5. Match versions

    Compare the full client and server version information.

  6. Check access controls

    Review whitelist, bans, operator settings, and plugin-based permissions.

  7. Review recent logs

    Look for a successful startup line or a clear plugin/configuration failure.

  8. Test without recent changes

    Remove the newest plugin or restore the previous configuration if the issue began immediately afterward.

Only one player cannot join

The problem is likely on that player’s client, account session, version, DNS, local firewall, network, or whitelist entry. Ask the player to restart the game, verify edition/version, re-enter the address, and test another network.

Nobody can join

Focus on server state, startup logs, address/port, platform status, firewall/routing, and recent server-side changes. Repeated restart clicks can make diagnosis harder.

Information for support

Send the exact error, edition, client version, server version, address format without exposing private credentials, time of failure, whether other players are affected, and the most recent relevant log lines. Never send your password.

Connection decision table

SymptomMost useful distinctionFirst test
Connection refusedHost reachable but nothing accepts the portConfirm server status and listening port
Timed outNo usable response reached the clientTest route, firewall, protocol and second network
Outdated / incompatibleProtocol or game version mismatchCompare exact client and server versions
Failed to verify usernameJava identity authentication failedCheck online mode, service status and system time
Only one player failsClient, route, account or local firewallTest a second account/device on the same network
Everyone fails after changeServer setting, software, firewall or updateRoll back the most recent controlled change

Collect evidence before restarting

Record the exact message, player edition, game version, address, port, server status, and timestamp. Copy the first relevant console error. A restart can make the symptom disappear temporarily while removing the original evidence.

DNS and address checks

PortalMine uses one public hostname with a required allocation port. Confirm that play.portalmine.com resolves to the game node, then connect with the exact address shown in the dashboard, such as play.portalmine.com:27733. Java requires TCP access to the allocated port; Bedrock requires UDP access to the allocated port.

Escalation checklist

  • Server type and version
  • Exact error text
  • Approximate time and timezone
  • Whether one or all players are affected
  • Networks already tested
  • Recent software, configuration, DNS, or plugin change

Troubleshoot by connection layer

LayerTypical failureBest first check
Server processOffline, crash, startup loop, not listeningDashboard state and console ready message
Edition and protocolJava/Bedrock mismatch or incompatible versionClient edition, exact version and server software
Address and DNSUnknown host or wrong destinationCopy the provided address; test direct address if documented
Port and routingRefused or timed outCorrect port format and whether any player can connect
AuthenticationSession, profile, online-mode or account-service errorRestart the client session and check service status
Client environmentMod mismatch, firewall, VPN, local network restrictionClean compatible profile and second network/device test

Symptom-specific interpretation

  • Unknown host: the name did not resolve; check spelling, DNS records, propagation, and whether a port was incorrectly placed in a hostname field.
  • Connection refused: the target was reached but no service accepted the connection; verify the server is running and listening on the expected port.
  • Timed out: packets or responses did not complete in time; compare networks, routing, firewall, platform state, and server load.
  • Outdated client/server: protocol versions do not match; select a compatible game version rather than changing unrelated settings.
  • Missing registry, channel, or mod: the client and server mod environments differ; compare loader, mod list, versions, dependencies, and configuration.

Controlled test sequence

  1. Confirm the server reaches a ready state.
  2. Test one owner client with the exact provided address.
  3. Compare a second player on a different network.
  4. Test a clean compatible client profile without optional mods or VPN.
  5. Compare direct address and custom domain only when both are documented.
  6. Record the exact error after each test and stop when the failed layer is isolated.

Evidence bundle for support

Provide server edition and software, server and client versions, exact connection address format with sensitive details redacted if required, time and timezone, client error text, server console lines at the same time, affected players and networks, and the last change. State whether anyone can connect successfully.

Validate the fix

A connection is not fully fixed until the player can join, remain connected, interact normally, change dimension if relevant, reconnect, and repeat the result after a controlled server restart. Keep the working configuration documented so future players receive the same edition, version, address, and extension instructions.