> For the complete documentation index, see [llms.txt](https://docs.nxcframework.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nxcframework.net/nexus-core-docs/start-here/upgrading.md).

# Upgrading

Moving to a newer version without breaking your server.

## The rule

**Upgrade a whole compatibility set at a time.** Do not upgrade one resource because its changelog looks appealing. Below 1.0.0 the framework's pieces depend on each other's contracts, and a mismatch produces failures that do not name their cause.

## Before you start

1. Read the changelog of every resource in the set. They record what changed and, more usefully, what is known not to work.
2. Read the set itself. It says what was verified and what was not.
3. Back up your database. Migrations are forward-only.

## Doing it

1. Stop the server.
2. Replace each resource directory with the new version.
3. Compare `server.cfg` against the new template — new settings arrive between versions, and an existing `server.cfg` never picks them up on its own.
4. Start, and watch for the lines in [Your first start](/nexus-core-docs/start-here/first-start.md).

Migrations apply automatically at startup and are recorded, so a restart does not re-run them.

## What does not survive

**Your `server.cfg` if you re-run the txAdmin recipe.** It deploys into a new directory and regenerates the file. Keep a copy first.

**Live sessions, on every restart.** The token signing key is regenerated at startup unless you have set one, so players reconnect. That is intended: a session token that outlives the server which issued it is a token nobody can revoke.

## Going backwards

Roll the resources back to the previous set's versions. **Migrations do not roll back** — a database that has had a newer migration applied may not work with an older resource, which is why the backup comes before the upgrade rather than after.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nxcframework.net/nexus-core-docs/start-here/upgrading.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.