Dennis HilkLinux Fix LabDE

NixOS & Configuration

A configuration option does not exist

Evaluation rejects an option before any system build. Check spelling, imported modules and the exact Nixpkgs revision instead of guessing replacement names.

Editorial source review: Start with the evidenceShare this guide
On this page
  1. Symptoms & scope
  2. Possible causes
  3. Diagnose safely
  4. Evidence-guided next steps
  5. References & review
  6. Related problems

Symptoms & scope

  • Evaluation reports that an option does not exist.
  • A copied configuration works against a different release or module set.

Relevant environment

NixOS module configurations using channels or a locked flake; option availability follows the evaluated Nixpkgs input.

Recognizable messages (synthetic examples)
error: The option `services.example.enable' does not exist. Definition values:

Check declaration scope and input revision; this is evaluation, not activation failure.

Possible causes

These are possible explanations, not a confirmed diagnosis. Several independent faults can coexist.

  • The option may be misspelled, renamed or supplied by a module that is not imported.
  • Documentation for another Nixpkgs revision may describe an option absent from the pinned input.

Diagnose safely

Run one command at a time in the relevant session. Read the explanation first. Uppercase placeholders need your own values; tools and privileges vary by distribution. These commands are displayed here and never executed by the website.

Check 1

Replace services.example with the rejected option namespace and /etc/nixos with your configuration checkout; rg only reads files.

rg -n 'services\.example' /etc/nixos

Interpret the result: Locate the defining module and its imports. The reported definition location is more useful than changing every similar name.

Check 2

Run in the flake checkout with jq installed; adapt the input name if Nixpkgs is not named nixpkgs.

jq '.nodes.nixpkgs.locked' flake.lock

Interpret the result: The locked revision identifies the option source to inspect. In a channel setup, inspect its actual source instead; a lock from another project is irrelevant.

Evidence-guided next steps

Use the option defined by this input

If the pinned release renamed or removed the option, migrate the setting using that revision's module documentation and release notes. Keep its type and semantic meaning, not merely a similar name.

Precautions: Build the candidate before activation. Changing system.stateVersion is not a way to select a newer option schema.

Recovery / rollback: Restore the configuration and lock file together if migration regresses behavior; retain a known-good generation.

Did this solution help you?

Share this solution#

Import the module that declares the option

If the option belongs to an external or custom module, add its intended import in the correct NixOS module scope. Verify that its input version is compatible with the rest of the configuration.

Precautions: Do not disable unmatched-option checks or add a freeform escape just to silence a typo. Imported modules can introduce additional defaults.

Recovery / rollback: Remove the added import and restore previous input pins and settings, then rebuild the former configuration.

Did this solution help you?

Share this solution#

References & review

This guide was prepared from primary project or distribution sources and reviewed on the date shown. This is an editorial source check, not evidence that a fix was reproduced on your hardware. Diagnostic log examples are synthetic fixtures. Version-dependent details must be checked against your installed release.