Introduction
This article addresses the commonly asked question regarding migrating HashiCorp Nomad clusters from the Enterprise edition to the Open Source (OSS) version. It outlines the technical limitations, provides a tested scenario, and makes clear recommendations for customers evaluating such transitions.
Scenario
A customer sought to migrate their existing Nomad Enterprise cluster to the OSS version by restoring Nomad Enterprise snapshots onto a newly provisioned Nomad OSS cluster.
Steps Attempted:
- Deployed a Nomad Enterprise cluster (v1.9.5+ent) on AWS EC2.
- Executed jobs using established namespaces, and integrated Consul (Enterprise Features)
- Took a cluster snapshot with
nomad operator snapshot save. - Provisioned a new Nomad OSS (v1.9.5) cluster with an identical topology.
- Attempted to restore the Enterprise snapshot onto the OSS cluster.
Observed Result:
The Nomad OSS server crashed with a panic, failing due to an unrecognized snapshot format (error: Unrecognized snapshot type: ). The server logs showed the OSS code was unable to parse raft entries relating to Enterprise features. Please see below complete error logs -
Aug 8 13:43:54 nomad-consul nomad[2245]: 2025-08-08T13:43:54.763+0530 [INFO] nomad.raft: snapshot restore progress: id=3-689-1742458434750 last-index=689 last-term=3 size-in-bytes=45190 read-bytes=39178 percent-complete="86.70%"
Aug 8 13:43:54 nomad-consul nomad[2245]: panic: failed to restore snapshot: failed to restore snapshot 3-689-1742458434750: Unrecognized snapshot type: [68]
Aug 8 13:43:54 nomad-consul nomad[2245]: goroutine 23 [running]:
Aug 8 13:43:54 nomad-consul nomad[2245]: github.com/hashicorp/raft.(*Raft).restoreUserSnapshot(0x4000a898c8, 0x40006d8230, {0x3838940, 0x4000a48948})
Aug 8 13:43:54 nomad-consul nomad[2245]: github.com/hashicorp/raft@v1.7.1/raft.go:1177 +0xab8
Aug 8 13:43:54 nomad-consul nomad[2245]: github.com/hashicorp/raft.(*Raft).leaderLoop(0x4000a898c8)
Aug 8 13:43:54 nomad-consul nomad[2245]: github.com/hashicorp/raft@v1.7.1/raft.go:879 +0x8cc
Aug 8 13:43:54 nomad-consul nomad[2245]: github.com/hashicorp/raft.(*Raft).runLeader(0x4000a898c8)
Aug 8 13:43:54 nomad-consul nomad[2245]: github.com/hashicorp/raft@v1.7.1/raft.go:575 +0x374
Aug 8 13:43:54 nomad-consul nomad[2245]: github.com/hashicorp/raft.(*Raft).run(0x4000a898c8)
Aug 8 13:43:54 nomad-consul nomad[2245]: github.com/hashicorp/raft@v1.7.1/raft.go:152 +0x54
Aug 8 13:43:54 nomad-consul nomad[2245]: github.com/hashicorp/raft.(*raftState).goFunc.func1()
Aug 8 13:43:54 nomad-consul nomad[2245]: github.com/hashicorp/raft@v1.7.1/state.go:149 +0x5c
Aug 8 13:43:54 nomad-consul nomad[2245]: created by github.com/hashicorp/raft.(*raftState).goFunc in goroutine 1
Aug 8 13:43:54 nomad-consul nomad[2245]: github.com/hashicorp/raft@v1.7.1/state.go:147 +0x84
Aug 8 13:43:54 nomad-consul systemd[1]: nomad.service: Main process exited, code=exited, status=2/INVALIDARGUMENT
Recommendation
It is not possible to downgrade or migrate a Nomad Enterprise cluster to OSS by restoring a snapshot or joining OSS servers to an Enterprise cluster.
- Nomad Enterprise snapshots are incompatible with OSS. Enterprise introduces features such as Namespaces, multi-Vault and Consul cluster integrations, multi-region deployments, and Dynamic Application Sizing (DAS), etc, that OSS does not support.
- Raft log entries related to Enterprise-only features cannot be parsed by OSS Nomad. Attempting to restore or join OSS servers leads to fatal errors and a panic state for the server.
- Official documentation explicitly states:
"A Nomad Enterprise cluster cannot be downgraded to the open source version of Nomad. Servers running the open source version of Nomad will panic if they are joined to a Nomad Enterprise cluster, due to raft entries relating to Enterprise features not being parseable by open source Nomad."
Additional Information
For more details on Nomad Enterprise exclusive features, see:
Also, If you need further clarification or migration guidance, please contact HashiCorp Support or your account representative.