> ## Documentation Index
> Fetch the complete documentation index at: https://nexohub.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Not breaking your network

> What NexoHub checks before it pushes, and how to undo an edit that got through.

One place to fix a mistake is also one place to make one, and a change reaches every
backend within seconds of you saving the file. Nothing asks you to confirm it first.

So two things sit between your editor and your players: nothing is pushed until it
parses, and every set of files that was pushed is kept.

## Nothing is pushed until it parses

Before any push, NexoHub reads every `.yml`, `.yaml`, `.json` and `.mcmeta` under
`nexo-data/` and parses it. If any of them fail, **nothing is pushed at all** and your
backends stay on the last files that did parse.

```
[NexoHub] Nothing was pushed: 1 file(s) do not parse.
  _shared/items/swords.yml line 14: could not find expected ':', while scanning a simple key
[NexoHub] The backends are still on the last files that parsed. Fix these and push again.
```

All of your files are held back, not just the broken one.

Turn it off with `sync.validate: false` on the proxy, though it is hard to see why you
would.

<Note>
  YAML problems name the file and the line. JSON problems name the file only. At most 15
  are listed, because fifty broken files are usually broken in one way and the first one
  is normally the cause.
</Note>

### What it does not catch

This checks that your files are readable, not that they are correct.

* **It does not check whether Nexo likes what a file says.** A tidy YAML file naming an
  item type that does not exist passes this check and still fails on the backend.
* **The JSON check is a floor.** It catches a missing brace or comma. It will accept some
  things a Minecraft client would not.
* **Files over 32 MB are skipped**, along with hidden files and `~` backups.

It is here to stop the one typo that takes every backend down at the same moment. Still
look at `/nexohub status` afterwards.

### Checking without pushing

```
/nexohub validate
```

Same check, no push. Run it after an adopt, or when you are halfway through an edit and
want to know before you save the last file.

The proxy also runs it on startup and prints anything it finds, so a file that has been
broken since the last restart does not stay quiet.

## Every set of files that was pushed is kept

A snapshot of `nexo-data/` is taken whenever your files change and pass validation.
Nothing is stored twice, so a restart, a `/nexohub push` and a touched but unedited file
all cost nothing.

Snapshots are also taken before the two things that overwrite your files wholesale:
`/nexohub adopt` and `/nexohub rollback` itself.

```
[NexoHub] 4 snapshot(s), newest first:
  1769517840000-5d935602  118 file(s)  3m ago  your edit
  1769516010000-0c47b7c6  117 file(s)  33m ago  your edit
  1769509220000-b41f0d7e  117 file(s)  2h ago  a manual push
  1769508900000-77c1a2e5  96 file(s)  2h ago  before adopting lobby
[NexoHub] /nexohub rollback <id> puts one back. The current files are snapshotted first.
```

The reason at the end is what caused it to be taken. `sync.snapshots` decides how many
to keep, 20 by default; `0` turns the history off.

## Going back

```
/nexohub rollback 1769516010000-0c47b7c6
```

The first few characters of the id are enough. An ambiguous prefix is reported rather
than guessed at.

```
[NexoHub] Restored 117 file(s) from 1769516010000-0c47b7c6, taken 36m ago.
[NexoHub] 2 file(s) added since then were removed.
[NexoHub] Pushed to 3 of 3 backend(s).
```

That second line is worth reading twice.

<Warning>
  A rollback **deletes files you added since the snapshot**. It has to, or the item you
  were undoing would still be there. A snapshot of your current files is taken first, so
  nothing is lost and you can roll the rollback back.
</Warning>

Restored files are checked on their way out like any other push. If a snapshot is old
enough to predate that check and does not parse, it goes back on disk but is not sent:

```
[NexoHub] The restored files do not parse, so nothing was pushed. That snapshot predates validation.
```

<Note>
  A snapshot holds the same files a push does, so hidden files, `~` backups and anything
  over 64 MB are not in it and will not come back. If you keep large source art in
  `nexo-data/`, back it up somewhere else too.
</Note>

## Trying it on one server first

Rolling back is the answer once players have seen a change. Staging is the answer before
they do.

```
/nexohub stage dev
```

Every backend except `dev` is held on the files as they are now. Edit `nexo-data/`, look
at `dev`, and finish either way:

```
/nexohub promote     the network gets what dev has been running
/nexohub discard     nexo-data/ goes back as the stage found it
```

Naming a server on `/nexohub push` does not do this and never did. A backend that is not
pushed to is parked on a long poll and pulls the same change a second later, so the only
way to keep an edit off your live servers is for the hub to go on serving them what they
already had. That is what a stage is.

The copy is taken when you run `stage`, not when you promote, so stage before you edit.
Anything changed beforehand is already on every backend.

<Warning>
  A stage keeps running until you promote or discard it, restarts included. That is
  deliberate, but it does mean a stage left on is a network that quietly stops receiving
  your edits. `/nexohub status` and `/nexohub doctor` both say when one is running, and the
  proxy log names it on every push it holds back.
</Warning>

Discarding is not destructive either. A snapshot is taken before `nexo-data/` is put
back, so the work you threw away is still in `/nexohub history`.

## Hearing about it

The console is not where most people find out something is wrong. Point `notify` at a
webhook and the failures come to you:

```yaml theme={null}
notify:
  webhook_url: "https://discord.com/api/webhooks/..."
  events:
    - validation_failed
    - reload_failed
    - collision
    - version_drift
    - rollback
```

Dropping `push` from that list leaves only things that need attention. The full list is
in the [proxy config](/reference/proxy-config#notifications).

`validation_failed` is the one worth having. A file that does not parse is *not* pushed,
so the network keeps working and nobody notices until someone asks why their new item
never showed up.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.