> ## 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.

# Troubleshooting

> Common messages and what to do about them.

<Tip>
  `/nexohub doctor` runs most of the checks below in one go. Start there.
</Tip>

## A server shows as `stale`

An empty server is not the reason. Backends report on their own, so a server nobody is
on still shows what it has. Check in this order:

<Steps>
  <Step title="Is it running?">
    A backend that is down or has no bridge shows as `never reported`, not `stale`.
  </Step>

  <Step title="Is the secret right?">
    The backend log says `Hub rejected the request: wrong hub.secret in config.yml`.
    Copy it again from the proxy.
  </Step>

  <Step title="Is the name right?">
    If you set `server_name` by hand it has to match your proxy's server list exactly.
    A backend that has never had a player and has no name set cannot ask for its files.
  </Step>

  <Step title="Can it reach the proxy?">
    `Could not reach the hub` means a firewall or a wrong `hub.address`. If the proxy
    sets `http.api_address`, the backend has to point at that port.
  </Step>

  <Step title="Is polling off?">
    `poll_seconds: 0` means that backend only syncs while somebody is on it. Its log
    says `Polling is off` at startup.
  </Step>
</Steps>

## `last reload failed` on a server that looks fine

```
last reload failed: Nexo produced no pack within 60s of the reload.
```

The pack took longer than 60 seconds to build. Big packs, slow disks and busy boots all
do this. Raise the timeout on the proxy:

```yaml theme={null}
defaults:
  reload_timeout_seconds: 180
```

If the pack builds in seconds and you still see this, something did go wrong. The
`Nexo said:` part of the message is what Nexo printed while it ran, which usually says
what.

<Note>
  A clean reload means a pack came out. It does not mean Nexo had nothing to complain
  about on the way, since NexoHub cannot tell an error from a progress line in Nexo's own
  output. If something still looks wrong, read that backend's console.
</Note>

## Nothing was pushed, files do not parse

```
[NexoHub] Nothing was pushed: 1 file(s) do not parse.
  _shared/items/swords.yml line 14: could not find expected ':'
```

Working as intended. Nothing is pushed, so your backends carry on with the last set that
worked. Fix the file and save again.

If the line looks fine, check the line above it. YAML errors get reported where the
parser gave up, which is often one line late.

## Backends disagree on versions

```
backends disagree on versions (lobby, smp on Nexo 1.26.0; pvp on Nexo 1.25.1)
```

Different Nexo or Minecraft versions build different packs from the same files, so
players re-download when they switch. Update the odd one out.

## Players are not getting the pack

Run `/nexohub doctor`.

On the default hosting the pack comes from an external host, and doctor says so:

```
note pack hosting is delegated to HERMES, so public_address is unused
```

Then the address is not your problem — skip to the sections below.

On `packs.host: proxy` doctor fetches your address from outside:

```
bad  nothing answered at http://your.proxy:8085; check the address, port and firewall
bad  public_address points at localhost, so only this machine can download the pack
```

It has to work from the internet, not just from your own network. Open it in a browser:
you should get a download.

## `Invalid PackServer type specified: HUB`

Nexo started before the bridge could register. Check `NexoHubBridge.jar` is in that
backend's `plugins/` and look just above this line for the bridge's own error.

Nexo carries on without a pack server, so nothing broken is sent to players.

## `NexoHubBridge is inactive: hub.secret is not set`

Copy `secret` from the proxy's `config.yml` into that backend's and restart. It is the
same on every backend.

Until you do, that backend leaves Nexo's pack serving alone rather than half-taking it
over, so players there get no pack. The rest of the network is fine.

## `players will not be able to download it`

The proxy was unreachable or refused the upload, so nothing was sent rather than a
broken link. Check the proxy is running and that `hub.address` and `hub.secret` are
right. It retries on the next reload.

## `The hub has no Nexo files of its own, so nothing was swept`

Normal right after installing on the proxy. Nothing is wrong and nothing was lost. A hub
with nothing in `nexo-data/` is never read as "delete this backend's files", even when
its bundle already carries other backends' generated output or shared plugin sources.

Do one of the two things the message says: `/nexohub adopt <server>` to fill it from a
backend you trust, or put files in `nexo-data/_shared/` yourself.

## `Could not reach the hub, continuing on the last synced files`

The backend started while the proxy was down. It uses the files it synced last time and
catches up on its own. You see this once, not once a minute.

## HUDs or models look wrong on one server

Usually a plugin naming clash. On the proxy:

```
[nexohub] Contributions lobby/betterhud and pvp/betterhud both define
assets/betterhud/font/a.json with different content.
```

Turn off `resourcepack-obfuscation` in BetterHUD's config.

Models can look wrong with no proxy warning, because BetterModel hands its output
straight to Nexo and the hub never sees it. Check the backend's log:

```
[NexoHubBridge] BetterModel's pack.use-obfuscation is on, so it names model parts by
this server's load order
```

Set `pack.use-obfuscation: false` in `plugins/BetterModel/config.yml` on every backend
and restart. Nexo obfuscates the merged pack anyway, so you give nothing away.

See [plugin packs](/guides/plugin-packs#two-settings-to-check).

## `/nexohub contributions` is empty, or missing a plugin

Check the backend's console for what it decided:

```
[NexoHubBridge] Published BetterHud (381 KiB) for the rest of the network.
[NexoHubBridge] Leaving MyBoughtPack.zip in external_packs/ alone: no plugin here says
it wrote it, so it is yours and stays on this backend.
```

If a plugin is missing entirely:

* `pack-type: none` in its config means it builds nothing.
* Its `build-folder-location` points outside `Nexo/pack/external_packs/`, so Nexo never
  imports it as an external pack. BetterModel ships that way on purpose.
* Its config will not parse, and the backend says so.

A **zip** you put in `external_packs/` yourself is never published, since no plugin
claims it. Put it in `nexo-data/_shared/pack/external_packs/` on the proxy instead, and
every backend gets it.

## I unpacked a pack on one backend and it went everywhere

A **folder** in `external_packs/` is published where a zip is not, because writing a
folder there is how some generators are collected. The backend says so:

```
[NexoHubBridge] mcmodels in external_packs/ is not something a plugin here says it
wrote, so it looks like yours. It is published to the rest of the network as this
backend's.
```

Move it to `nexo-data/_shared/pack/external_packs/` on the proxy and delete it from the
backend. To keep it on that one backend, name it in `contribute_exclude`.

## My packs did not move when I ran `/nexohub adopt`

Adoption never carries `pack/external_packs/`, because most of it is rebuilt on every
backend anyway. It lists what it left, and flags the ones no plugin accounts for:

```
[nexohub] 1 of those are not accounted for by any plugin there.
```

Those are yours. Upload them once to `nexo-data/_shared/pack/external_packs/`. The rest
need nothing.

## A pack I deleted from `external_packs` keeps coming back

Both halves put it back. The plugin writes it again on its next run, and the hub hands
your own contribution back as `_hub-<name>-<id>`.

Stop whatever generates it — remove the HUD from BetterHUD's config, uninstall the
plugin, or add the folder to `contribute_exclude` — and it clears on the next reload.

If the backend cannot withdraw it itself, drop it by hand:

```
/nexohub contributions drop lobby oldhud
```

## Multipack templates show the main pack

Your host hides the pack hash in the URL, and multipack needs it. `POLYMATH` and
`LOBFILE` do this. Switch to `hermes`, `s3` or `proxy`. See
[hosting](/guides/hosting#if-you-use-multipack).

## Players re-download when switching servers

```
/nexohub status
```

```
same files, different packs (lobby on a6efb696; survival_hub on a8ba1e90)
```

Backends on the same files should never reach this, since the network picks one pack and
everyone serves it. Seeing it anyway means one of:

* An old `NexoHubBridge.jar` on those backends. Update it everywhere.
* They could not reach the hub when they generated. Fix the connection and push again.
* One holds pack content the others do not, so the files only match on paper. Check
  `/nexohub contributions`.

If they are on *different* files they are supposed to differ, and nothing is wrong. That
is a per-server override, or different versions.

<Note>
  `Pack.obfuscation.type: NONE` does not help here, though it looks like it should. Two
  servers with identical files still build different bytes with obfuscation off entirely.

  If there is no download bar and players only see the pack applying, nothing is being
  re-downloaded — that is the pack being sent again, which is NexoProxy's job to suppress.
</Note>

## An edit made things worse

```
/nexohub history
/nexohub rollback <id>
```

A copy is kept every time your files change. See [safety](/guides/safety#going-back).

## Disk filling up on the proxy

```
note plugins/nexohub/ uses 62 MiB (2 pack(s), 4 snapshot(s))
```

Old packs clean up automatically. `/nexohub packs prune` does it now, `packs.keep` and
`sync.snapshots` set the limits.


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