Should I update stateVersion

Help
1

I am setting up my new homeserver and decided to use NixOS on it. I already have one running some services and want to migrate everything to the new one. I prefer to use stable channels unless there is a specific reason to do otherwise.
One of the services I currently run on my current homeserver is Jellyseerr. ~1.5 months ago they renamed themselves to Seerr in their 3.0 update. Unfortunately nixos-25.11 doesn’t even have the service yet so I installed it using nixos-unstable overlay and manually imported the services using this:
modules = [ … (import “${nixpkgs-unstable}/nixos/modules/services/misc/seerr.nix”) … ]
and

services.seerr = {
enable = true;
package = pkgs.unstable.seerr;
};

Now sudo nixos-rebuild switch --flake . gives me this error:
trace: Obsolete option services.jellyseerr' is used. It was renamed to services.seerr’.
I checked the package and the lines 11, 41 and 58 might be connected to this.
I read the release notes and Seerr was mentioned in it and none of my other services were, so it seems to me that changing the stateVersion shouldn’t break anything.

My config can be found here

Should I bump stateVersion to 26.05 or is there a better solution?

1 Like
2

short answer: no

long answer: probably not

longer answer: you can if you really want to, but carefully read release notes & diff the resulting nixosSystem

also see FAQ/When do I update stateVersion - Official NixOS Wiki

especially:

you cannot update it safely without a complete understanding of all NixOS modules you are using, directly or indirectly

and

it is used to inform NixOS what versions of packages you might have previously installed. This is used to ensure correct data migration for certain packages

Regarding seerr: the trace is just a warning, not a hard error. I think the trace is just a side effect of pulling in the module from unstable, nothing to worry about really.

3

No. That’s deliberately preceded with “Generally”, it’s just the most common use case. Read the subsequent paragraph:

The current and historic lack of a clear definition of what it does is part of why it cannot be updated.

NixOS modules use it for anything and everything, the effect of changing it is effectively unpredictable. Just don’t touch that number.

I’ll have to remove that first paragraph, it’s clearly somehow still misleading. I still think we should change that string from a version number to some arbitrary hash to make people completely incapable of changing it.

This is notably the wrong conclusion:

Diffing the system is useless, since the changes will be at a script/application level and invisible. You’d have to actively read all the source code, and understand it.

Since system.stateVersion is internal API and should not be touched by users, the release notes will not talk about changes that would be affected by it, unless they explicitly say the exact words that you can either remove or must edit the stateVersion.

That caveat is basically there so that we can eventually completely remove stateVersion without confusing users, since that’s at least in theory possible, but I don’t see this happening anytime soon in practice.

Why do you want to change it anyway? It’s not going to make that warning disappear.

That’s just telling you that an option was renamed, which isn’t affected by stateVersion at all. You don’t share enough code for me to tell why that’s showing up, did you remember to add the old module to disabledModules?

4

I just want to prevent a future migration. I don’t see a reason to install Seerr with some configuration that will change in the near future. Currently the package has this line:
default = if useNewConfigLocation then "/var/lib/seerr/" else "/var/lib/jellyseerr/config";
which I assume is an example how stateVersion can break things. It seems logical to me to use the upcoming more naturally named directory already, as I am installing it on a new system, that I can re-install without any major pain if really needed. I am just used to the Docker image, which was always up-to-date, so I could always follow the migration guide if an major update came.

I think the warning is caused by my potentially sub-optimal nixos-unstable overlay. I am not really bothered by the warning, but if you want to help it was probably caused by these commits: “Add support for nixos-unstable packages” and “Add Seerr (Jellyseerr)”

5

Understood, but to achieve that you’d have to first perform migrations for all services you currently have installed.

That is also why I don’t realistically see us deprecating system.stateVersion; we will never be able to migrate all users, so in practice all these backwards-compatibility hacks will have to be maintained ad infinitum. system.stateVersion basically means that you will never have to migrate anything, and cannot even realistically prevent the need for it in the first place.

That’s the unfortunate reality of any and all uses of system.stateVersion, and why I personally think the option should be avoided where possible - especially like this, a directory rename is basically just done for vanity. This is a very inconsiderate change. Wonder if it’s too late to revert.

1 Like
6

The thing is that I migrating everything isn’t the end of the world for me. I am still in the setup phase, I have like 10+ services to move (convert to Nix form) from my current/previous machine. I was actually planning on re-installing from scratch to test how declarative my config really is and which things I have configured manually.
So would switching to stateVersion 26.05 be valid choice then?
And btw are xx.05 the same thing as xx.11 or is there some difference (e.g. LTS)?

Yeah that’s the problem with big projects that a lot of people depend on, you can never really change stuff that made it out of testing.

Incrementally salvaging stateVersion
7

If you don’t care about the state on-disk, yeah, I suppose it doesn’t need to be versioned.

8

The root issue here (the warning) has nothing to do with stateVersion, but the renamed module. disabledModules = [ "services/misc/jellyseerr.nix" ] would do the trick.

(Or, if the services are Close Enough, services.jellyseerr.package = pkgs.seerr and not using the module from unstable would be a possible alternative.)

9

That just removes the warnings; it turns out that the intent really is just not to have that directory rename:

1 Like
10

Okay, thank you everyone for advice!
Looks like I have stumbled on a current NixOS limitation/flaw, so I’ll see where this thread goes and provide help where necessary.