Missing `system.stateVersion`

After recently converting my NixOS configs to a flake, I have been getting this warning during build:

warning: system.stateVersion is not set, defaulting to 22.05. Read why this matters on https://nixos.org/manual/nixos/stable/options.html#opt-system.stateVersion.

I understand broadly what system.stateVersion is for, but I’m surprised I’ve never had it set in my configuration.nix file before (I checked the git history and it’s never mentioned, aside from when I added a home.nix file, but also my configuration files are older than their existence in Git by many years).

The warning message says it’s defaulting to 22.05, so I’ve gone ahead and made that explicit in my configuration. My question is, how can I be sure this won’t cause a problem? I have been running NixOS on this computer for seven or eight years, so I am worried that setting the state version to 22.05 may cause some byzantine failure that I won’t know about until it hits. Is there a way to inspire confidence that this won’t happen?

stateVersion has always defaulted to the current release, so It’s been changing underneath you this whole time. Stopping the change by setting it to the current release and then leaving it in future release upgrades is the right move, and definitely won’t make anything worse than just leaving it unset already did. In short, setting it to 22.05 won’t change your current system at all, but will prevent a change at the next release upgrade.

Normally, stateVersion is added to your configuration.nix by nixos-generate-config during the install process. Perhaps you went about the install in an unusual way?


It does bring up an interesting general question; when something gated by stateVersion changes, how can I know about it?

Keeping stateVersion set to what it was at installation time seems sensible, but I’ve seen at least one situation in which bumping stateVersion was required because of some eventual incompatibility. When that happens, how am I supposed to know what things will change from under my feet?

1 Like

I think you need to go through these lists for each of the the intermediate releases: Nix - NixOS 22.05 manual

Hm, I was under the impression that that doesn’t list the changes related to system.stateVersion, at least not exhaustively. But now I notice at least a handful of mentions. Is there a statement anywhere about how exhaustive that is?

If it is exhaustive, then the answer for @roni is “go through the versions you updated between since you first installed NixOS and see about any backwards-incompatibilities that mention system.stateVersion, check what your system ended up actually doing in practice and manually migrate anything that ended up being weirdly duplicated”.

That would be much easier if the changelog was actually one page per version, rather than a single page containing everything…


I did a boring old “regular” install, but it was a long, long time ago, and I assume that at some point, I misunderstood system.stateVersion and removed it.

But I seem to also be a boring user of NixOS–I went through the release notes as you suggested and I’ve never used any of the features impacted by stateVersion changes. Thanks for the advice!

1 Like