# What happens when a connection fails

> If your server will not start, will not answer or players cannot join, NetCraftGames does not just say "failed". It emails the specific problem, likely causes, concrete fix steps and an example, tells you whether the clock is paused, and you resubmit a new release.

*NetCraftGames (NCG) by Charging Bull Software. Last updated: 2026-10-03. Canonical page: https://netcraftgames.com/connection-failures/*

## The short answer

Every failure NetCraftGames can detect maps to a fixed, tested piece of advice: the problem in plain words, likely causes, numbered fix steps, a code or command example and exactly how to resubmit. The advice is pre-written and fixed, not generated by a model on the fly, so it is the same every time and cannot be talked into saying something wrong. An optional AI layer may add an explanation on top, but never replaces it.

## What the email contains

Each failure email is written to be read on a phone with no context. It says:

1. What it is about: which game and release.
2. Progress so far: which stages passed and which failed.
3. Why we are writing: what we need from you.
4. Full context: the problem, the likely causes and the evidence.
5. Options and a recommendation: what to fix first.
6. What happens next: how to resubmit and what the clock is doing.

It never contains credential values. It is built only from failure codes, sanitized context, file names that passed a path sanitizer and fixed advice text, and a final check rejects anything shaped like a secret.

## The failures it detects

| Failure | What it means | The usual fix |
| --- | --- | --- |
| Upload is not a safe `.tar.gz` | Unsafe paths, links, special permission bits, or too many entries | Repack with GNU tar from a clean folder with no links |
| Manifest rejected | A required field is wrong or a probe uses an undeclared port | Copy the template for your engine and list every port |
| No Linux x86-64 server found | Windows, macOS, ARM, source only, or a client build | Build a Linux x64 dedicated server and set the executable bit |
| Port not listening | The server bound to `127.0.0.1`, or uses another port or protocol | Bind `0.0.0.0` on the declared port |
| Health check failed | The server answers, but not with the declared reply | Add a cheap route or UDP reply and declare it exactly |
| Join check failed | The game-level probe did not return the declared answer | Add an unauthenticated "accepting players" reply |
| Hash mismatch | The file differs from the declared SHA-256 | Use the digest of the exact uploaded file |
| Crash at startup | Missing library, wrong architecture, needs a display or GPU | Reproduce in a clean Linux container; use headless flags |
| Wrong transport | Declared transport differs from the code | Declare what the server really listens on |
| Engine mismatch | Declared engine differs from the code | Declare the engine you ship |
| Credentials in the upload | A secret was packed into files | Rotate it, remove it, read it from the environment |
| Build too large | Client assets, symbols or caches packed | Use a server build target and strip the folder |
| Unsupported engine | An engine id that is not on the supported list | Use a listed lane; for your own raw TCP or UDP protocol choose Custom native TCP/UDP (direct) |
| Declared stack not found (advice, never blocks) | A Unity build declared as Mirror or NGO holds none of those assemblies, a WebSocket declaration shows no WebSocket server, or the code is a custom native server | Declare Custom native TCP/UDP (direct) and supply a join probe, or ship the library you declared |
| Needs a newer glibc than the worker image | A shipped Linux program or add-on was linked against a glibc newer than 2.39 | Rebuild on Ubuntu 24.04 or in an `ubuntu:24.04` container |
| Networking not found | No server networking in what we could read | Upload the dedicated server build and declare ports by hand |
| Unsafe startup script | Download-and-run, privileged or destructive commands | Launch a plain executable; ship everything in the archive |
| WebSocket path unsupported | The code serves its WebSocket at a path such as `/ws` and the manifest declares no `wsPath` | Add `wsPath` (for example `"/ws"`) to the manifest, or accept upgrades at `/` |
| WebSocket path does not match | The manifest's `wsPath` differs from the path the code serves (for socket.io, the fixed query is missing) | Make the two agree |
| Project folder uploaded | Source files with `package.json` or `requirements.txt` and no start script | Run `ncg pack . --node --install` (or `--python`) and upload what it builds |
| Packages missing (Node) | `package.json` lists dependencies but there is no `node_modules` | `ncg pack . --node --install` |
| Packages missing (Python) | `requirements.txt` lists packages but no vendored wheels | `ncg pack . --python --install` |
| Node version not supported | `engines.node` cannot be satisfied by Node 24 | Change `engines` to allow 24, or ship your own node in the archive |
| Add-on built for another system | A `.node` or Python extension is for Windows, macOS, ARM or musl | Install with `ncg pack`, which asks for Linux x64 glibc builds only |
| Add-on built for another Node | A native add-on (uWebSockets.js) was built for a different Node ABI | Use the add-on version that supports Node 24, or use `ws` |
| Start script points at nothing | The launcher starts a file that is not in the archive | Fix the path in the launcher, or pack again |
| Python wheel for another system | A Python extension is not cp312 manylinux x86_64 | `ncg pack . --python --install` |
| Framework needs plain web requests | Colyseus (matchmaking over HTTP) | Move to plain WebSocket, or use a lane that fits |
| Install scripts present (advice) | `package.json` has install or postinstall scripts | They never run on our servers; make sure the game does not depend on them |
| Timeout | The server took too long to become ready | Open the socket first, load content after; reply if it repeats |

## A worked example: nothing was listening on UDP 7777

**Problem.** Your server process started, but UDP port 7777 did not accept traffic.

**Likely causes.** It binds `127.0.0.1` instead of `0.0.0.0`; it uses a different port than the manifest declares; the manifest says UDP but the game opens TCP; or it needs longer than the wait time to load before opening its socket.

**Fix.** Bind all interfaces on the declared port, make the start command pass the same port the code listens on, open the socket early in startup, and reproduce locally in a clean Linux container. For a Node server:

```javascript
const port = Number(process.env.PORT ?? 7777);
const wss = new WebSocketServer({ host: '0.0.0.0', port });
```

## Who has to fix it, and the clock

Each failure is classed as the owner's, the platform's or undetermined. Only when every blocking problem is the owner's does the 24-hour clock pause; platform and undetermined problems keep it running and alert a human operator. See [the 24-hour promise](https://netcraftgames.com/24-hour-promise/).

## How to resubmit

1. Rebuild your server with the fix and upload the new `.tar.gz` to the same game.
2. Create a new release version, for example 1.0.3 to 1.0.4, with the new upload's digest, then choose Check.
3. Your clock resumes when the new release is received, and the dashboard shows the exact time remaining.

## What is not proven yet

> **Pre-launch**
>
> Email delivery to real inboxes has not been observed end to end, and no customer has received one of these emails. Both are launch checks that must pass before NetCraftGames opens. See [launch status](https://netcraftgames.com/status/).


## Frequently asked questions


### What happens if my game server will not connect?

NetCraftGames emails you the specific problem, the likely causes, numbered fix steps with an example, and whether the 24 hour clock is paused. You fix the build, upload a new release and the clock resumes. The advice comes from a fixed table of known failures, so it is consistent and never invents a diagnosis.

### Do failure emails ever include my passwords or keys?

No. Failure emails are built only from failure codes, sanitized context, vetted file names and fixed advice, and a final check blocks anything shaped like a secret. If credentials are found in your upload, the email names the kind and file, never the value, and tells you to rotate them.

## Related pages

- [The 24-hour promise, with the conditions stated plainly](https://netcraftgames.com/24-hour-promise/): What NetCraftGames means by "online and server ready in 24 hours": a processing target, when the clock starts and pauses, exclusions and open questions.
- [What the AI reads, and what it never does](https://netcraftgames.com/trust/): The exact boundaries of AI in NetCraftGames: what a static reader and optional AI see in your submission, and the things that never happen, with limits stated.
- [What a connection config file must contain](https://netcraftgames.com/guides/connection-config-file-contents/): What a deployment manifest and a player connection config must contain for a hosted multiplayer server, with a real example and the rules that cause rejections.