Skip to content
CatalystCatalyst Docs

Migration

The migration center (Admin → Migration) imports a Pterodactyl panel into Catalyst as a tracked job: test the connection first, map the target nodes, then run. Each job exposes phase- and step-level status, so you can retry a failed step, pause, resume, or cancel without starting over. Migration requires an administrator account.

Prerequisites

Section titled “Prerequisites”
  • A Catalyst node that is online with enough free capacity for the servers you are moving. Migration refuses to start with no online target node.
  • The source panel’s Application API Key (ptla_…). It must be allowed to change server feature limits: when a source server has no backup slots (or all of them are used), the job raises its backup limit so it can create the migration backup. If that call fails, that server’s backup step is skipped.
  • The source panel’s Client API Key (ptlc_…) if you want backups, server files, schedules and subusers migrated. Without it those steps are skipped. Create it in Pterodactyl under API Credentials → Client API.
  • Templates and nests are imported automatically by the job — you do not have to run egg imports first, though doing so lets you fix a template before a large run.

Run a migration

Section titled “Run a migration”
  1. Open Admin → Migration. The New Migration tab is the default.
  2. Under Connect, enter the source Panel URL and Application API Key, plus the optional Client API Key (for file migration).
  3. Select Test Connection. The panel reports the source’s locations, nodes, nests, users, and servers, and warns about servers with no free backup slots.
  4. Choose the Migration Scope:
    • Full Migration — every source node, mapped onto Catalyst nodes.
    • Node by Node — only the source nodes you select.
    • Server by Server — map individual servers to a Catalyst node.
  5. Under Map Pterodactyl Nodes to Catalyst Nodes (or Map Pterodactyl Servers… for server scope), pick the target node for each entry. Click an entry to preview what will be imported. The scope applies to the whole job, so pick one before mapping.
  6. Select Start Migration. The Start Migration button stays disabled until the connection test succeeds, every entry required by the scope is mapped, and at least one target node is online.
  7. The view switches to the Active Migration tab. Work the phases top to bottom: Validation, Locations, Templates (Nests & Eggs), Users, Servers, Subusers, Databases, Schedules, Backups, Server Files. Use Pause / Resume to control the job, Cancel to stop it, and the retry button on a failed step to re-run just that step. A failed step does not mean a failed migration.
  8. Finished jobs move to the History tab with their step counts.

Safest order of operations

Section titled “Safest order of operations”
  1. Run the connection test and read the warnings before starting anything; fix backup slots or missing keys on the source panel first.
  2. Migrate a pilot server (or a small node) and complete the full cycle — import, install, start, join, backup, restore — before a large run.
  3. Run the rest in batches, during low-traffic windows, biggest risk first.
  4. Verify each batch with server owners before moving on.
  5. Keep the source panel and servers stopped-but-present until owners confirm. The rollback is to turn the old server back on.

Per-server checklist

Section titled “Per-server checklist”
  • Files and worlds intact (compare sizes and spot-check).
  • Databases moved and plugins reconnecting.
  • Startup variables and schedules recreated (tasks).
  • Backups running on the new side before DNS or addresses switch.
Section titled “Related”