Troubleshooting

Hidden storage is mounted but activation fails

Check the expected directory tree first. Missing work directories, wrong permissions, or a backend that does not behave like a normal Linux filesystem are common causes.

Activation is slow

The first full activation can be much slower than later ones because it includes NixOS activation work. If repeated runs stay slow, inspect your rebuild path rather than assuming the overlay layer is the only cause.

Deactivation did not leave you confident

Do not ignore that feeling. Verify state, inspect what changed, and reboot into a known decoy state if needed.

The docs are not enough for your environment

That usually means your deployment has moved beyond the safe generic path. Treat your local runbook as part of the system and document it with the same honesty as the public docs.