Error handling - Revision history

Axka: Fix link "Nix manual: Assertions"

2025-06-09T16:14:55Z

Fix link "Nix manual: Assertions"

← Older revision		Revision as of 16:14, 9 June 2025
Line 19:		Line 19:
	The nix language has a construct to help with printing messages.		The nix language has a construct to help with printing messages.

	* '''assert''': throw an error (see [https://nixos.org/manual/nix/stable/language/~~constructs~~.html?highlight=assert#assertions Nix manual: Assertions])		* '''assert''': throw an error (see [https://nixos.org/manual/nix/stable/language/syntax.html?highlight=assert#assertions Nix manual: Assertions])

	The nix language also comes with some related [https://nixos.org/manual/nix/stable/language/builtins.html builtin functions]:		The nix language also comes with some related [https://nixos.org/manual/nix/stable/language/builtins.html builtin functions]:

imported>Carschandler: The previous example for config.warnings was returning a list inside of a list, which doesn't work properly

2024-01-19T12:39:12Z

The previous example for config.warnings was returning a list inside of a list, which doesn't work properly

← Older revision		Revision as of 12:39, 19 January 2024
Line 8:		Line 8:
	lib.warn "This is a sample warning message."		lib.warn "This is a sample warning message."
	{		{
	config.warnings = [		config.warnings = (
	# Some NixOS module: throw error, if services.foo.bar == true		# Some NixOS module: throw error, if services.foo.bar == true
	(lib.optionals config.services.foo.bar "This is also a sample warning message, but invoked differently.")		lib.optionals config.services.foo.bar "This is also a sample warning message, but invoked differently."
	];		);
	}		}
	</syntaxHighlight>		</syntaxHighlight>

imported>Pogobanane at 18:28, 9 September 2023

2023-09-09T18:28:11Z

← Older revision		Revision as of 18:28, 9 September 2023
Line 74:		Line 74:
	</code> ([https://github.com/NixOS/nix/blob/b17c4290cf61d8a0386817b87231762c175097c5/tests/lang/eval-okay-getattrpos.nix example]) which returns the line and column of where an attribute is defined. It is undocumented and considered bad practice.		</code> ([https://github.com/NixOS/nix/blob/b17c4290cf61d8a0386817b87231762c175097c5/tests/lang/eval-okay-getattrpos.nix example]) which returns the line and column of where an attribute is defined. It is undocumented and considered bad practice.

	For NixOS options unsafeGetAttrPos doesn't work, but the module system itself records that information: to find the location of <code>config.networking.hostName</code>, use <code>:p options.networking.hostName.declarationPositions</code>.		(soon to come [https://github.com/NixOS/nixpkgs/pull/249243 github PR]): For NixOS options unsafeGetAttrPos doesn't work, but the module system itself records that information: to find the location of <code>config.networking.hostName</code>, use <code>:p options.networking.hostName.declarationPositions</code>.

	== References ==		== References ==

imported>Pogobanane at 18:22, 9 September 2023

2023-09-09T18:22:48Z

← Older revision		Revision as of 18:22, 9 September 2023
Line 74:		Line 74:
	</code> ([https://github.com/NixOS/nix/blob/b17c4290cf61d8a0386817b87231762c175097c5/tests/lang/eval-okay-getattrpos.nix example]) which returns the line and column of where an attribute is defined. It is undocumented and considered bad practice.		</code> ([https://github.com/NixOS/nix/blob/b17c4290cf61d8a0386817b87231762c175097c5/tests/lang/eval-okay-getattrpos.nix example]) which returns the line and column of where an attribute is defined. It is undocumented and considered bad practice.

	For NixOS options unsafeGetAttrPos doesn't work, but the module system itself records that information: to find the location of <code>config.networking.hostName</code>, use <code>:p options.networking.hostName.~~definitionsWithLocations~~</code>.		For NixOS options unsafeGetAttrPos doesn't work, but the module system itself records that information: to find the location of <code>config.networking.hostName</code>, use <code>:p options.networking.hostName.declarationPositions</code>.

	== References ==		== References ==

imported>Pogobanane: mention nixos modules definitionsWithLocations

2023-09-09T18:15:46Z

mention nixos modules definitionsWithLocations

← Older revision		Revision as of 18:15, 9 September 2023
Line 69:		Line 69:
	To summarise debugging approaches discussed in this article, you can use <code>break</code> to debug nix code, <code>breakpointHook</code> to debug nix builds and interactive tools to debug NixOS tests.		To summarise debugging approaches discussed in this article, you can use <code>break</code> to debug nix code, <code>breakpointHook</code> to debug nix builds and interactive tools to debug NixOS tests.

	~~Another tool that~~ can ~~be useful to improve error messages is~~ <code>builtins.unsafeGetAttrPos		To find the location where variables get defined, you can use the following tools:
	</code> ([https://github.com/NixOS/nix/blob/b17c4290cf61d8a0386817b87231762c175097c5/tests/lang/eval-okay-getattrpos.nix example]) which returns the line and column of where an attribute is defined. ~~Currently this seems to be limited to attributes defined in the same file though,~~ is undocumented and considered bad practice.
			For bare nix code, use <code>builtins.unsafeGetAttrPos
			</code> ([https://github.com/NixOS/nix/blob/b17c4290cf61d8a0386817b87231762c175097c5/tests/lang/eval-okay-getattrpos.nix example]) which returns the line and column of where an attribute is defined. It is undocumented and considered bad practice.

			For NixOS options unsafeGetAttrPos doesn't work, but the module system itself records that information: to find the location of <code>config.networking.hostName</code>, use <code>:p options.networking.hostName.definitionsWithLocations</code>.

	== References ==		== References ==

imported>Pogobanane: mention builtins.unsafeGetAttrPos

2023-05-04T16:16:39Z

mention builtins.unsafeGetAttrPos

← Older revision		Revision as of 16:16, 4 May 2023
Line 68:		Line 68:

	To summarise debugging approaches discussed in this article, you can use <code>break</code> to debug nix code, <code>breakpointHook</code> to debug nix builds and interactive tools to debug NixOS tests.		To summarise debugging approaches discussed in this article, you can use <code>break</code> to debug nix code, <code>breakpointHook</code> to debug nix builds and interactive tools to debug NixOS tests.

			Another tool that can be useful to improve error messages is <code>builtins.unsafeGetAttrPos
			</code> ([https://github.com/NixOS/nix/blob/b17c4290cf61d8a0386817b87231762c175097c5/tests/lang/eval-okay-getattrpos.nix example]) which returns the line and column of where an attribute is defined. Currently this seems to be limited to attributes defined in the same file though, is undocumented and considered bad practice.

	== References ==		== References ==

imported>Pogobanane at 14:17, 4 May 2023

2023-05-04T14:17:07Z

← Older revision		Revision as of 14:17, 4 May 2023
Line 67:		Line 67:
	<!-- put debugging into a heading for search engine optimisation -->		<!-- put debugging into a heading for search engine optimisation -->

	~~As mentioned above~~, you can use <code>break</code> to debug nix code, <code>breakpointHook</code> to debug nix builds and interactive tools to debug NixOS tests.		To summarise debugging approaches discussed in this article, you can use <code>break</code> to debug nix code, <code>breakpointHook</code> to debug nix builds and interactive tools to debug NixOS tests.

	== References ==		== References ==

imported>Pogobanane: add examples

2023-05-04T14:15:05Z

add examples

← Older revision		Revision as of 14:15, 4 May 2023
Line 1:		Line 1:
	This page is a collection of facilities and tools from nix, nixpkgs and NixOS for error handling and debugging. You can use them to convey configuration errors to users or to debug nix expressions trough interactive or print debugging.		This page is a collection of facilities and tools from nix, nixpkgs and NixOS for error handling and debugging. You can use them to convey configuration errors to users or to debug nix expressions trough interactive or print debugging.

	~~{{Expansion\|This page is currently being worked on (04~~.05.~~2023)~~ and ~~desperately needs usage examples~~.}}		In most cases you will want to stick to the highest level abstraction: <code>config.warnings</code> or <code>lib.warn</code> and its relatives.

	~~In most cases you will want to stick to the highest level abstraction~~: config.warnings or lib.~~assertMsg~~		<syntaxHighlight lang=nix>
			{ config, lib, ... }:
	<~~give examples for both~~>		# in any nix code:
			lib.warn "This is a sample warning message."
			{
			config.warnings = [
			# Some NixOS module: throw error, if services.foo.bar == true
			(lib.optionals config.services.foo.bar "This is also a sample warning message, but invoked differently.")
			];
			}
			</syntaxHighlight>

	== Nix ==		== Nix ==
Line 11:		Line 19:
	The nix language has a construct to help with printing messages.		The nix language has a construct to help with printing messages.

	* '''assert''': throw an error (see [https://nixos.org/manual/nix/stable/language/constructs.html?highlight=assert#assertions; Nix manual: Assertions])		* '''assert''': throw an error (see [https://nixos.org/manual/nix/stable/language/constructs.html?highlight=assert#assertions Nix manual: Assertions])

	The nix language also comes with some related [https://nixos.org/manual/nix/stable/language/builtins.html; builtin functions]:		The nix language also comes with some related [https://nixos.org/manual/nix/stable/language/builtins.html builtin functions]:

	* '''throw''': throw an error with a message		* '''throw''': throw an error with a message
Line 22:		Line 30:
	* '''tryEval''': catch throws and asserts		* '''tryEval''': catch throws and asserts

	Commonly, assert is combined with throw to generate meaningful error messages: <code>assert condition \|\| throw "message";</code>. This pattern is essentially how <code>lib.assertMsg</code> works (see Sec. nixpkgs). <ref>[https://github.com/NixOS/nixpkgs/issues/154292; throw vs assert discussion]</ref>		Most of those functions (nix builtins as well as nixpkgs lib functions) take an expression <code>e</code> as their last argument which they return unmodified. Thus they are chained in front of some expression:

			<syntaxHighlight lang=nix>
			a = builtins.trace "trace message" {
			# what should be assigned to a
			};
			</syntaxHighlight>

			Commonly, assert is combined with throw to generate meaningful error messages: <code>assert condition \|\| throw "message";</code>. This pattern is essentially how <code>lib.assertMsg</code> works (see Sec. nixpkgs). <ref>[https://github.com/NixOS/nixpkgs/issues/154292 throw vs assert discussion]</ref>

	== nixpkgs ==		== nixpkgs ==
Line 28:		Line 44:
	There are three main facilities for printing errors and do print debugging in nixpkgs:		There are three main facilities for printing errors and do print debugging in nixpkgs:

	* lib.trivial.* (see [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-trivial; nixpkgs manual: lib.trivial])		* lib.trivial.* (see [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-trivial nixpkgs manual: lib.trivial])
	** lib.'''throwIf''' and throwIfNot		** lib.'''throwIf''' and throwIfNot
	** lib.'''warn''', '''warnIf''' and warnIfNot		** lib.'''warn''', '''warnIf''' and warnIfNot
	* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-debug; lib.'''debug'''.*]: tracing functions with some pretty printing <ref>[http://ryantm.github.io/nixpkgs/functions/library/debug/#sec-functions-library-debug; Nixpkgs/docs: lib.debug]</ref>		* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-debug lib.'''debug'''.*]: tracing functions with some pretty printing (e.g. <code>lib.debug.traceIf</code>) <ref>[http://ryantm.github.io/nixpkgs/functions/library/debug/#sec-functions-library-debug Nixpkgs/docs: lib.debug]</ref>
	* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-asserts; lib.'''asserts'''.*]: assert functions		* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-asserts lib.'''asserts'''.*]: assert functions (e.g. <code>lib.asserts.assertMsg</code>)

	These facilities also expose their attributes directly via <code>lib.*</code> (e.g. <code>lib.throwIf</code>).		These facilities also expose their attributes directly via <code>lib.*</code> (e.g. <code>lib.throwIf</code>).

	Nixpkgs also has a debugging facility like nix's <code>break</code>: the [https://nixos.org/manual/nixpkgs/stable/#breakpointhook; breakpointHook].		Nixpkgs also has a debugging facility like nix's <code>break</code>: the [https://nixos.org/manual/nixpkgs/stable/#breakpointhook breakpointHook].

	== NixOS ==		== NixOS ==

	The NixOS module system again wraps these library functions and makes them available via module options (see [https://nixos.org/manual/nixos/stable/index.html#sec-assertions-warnings; NixOS manual: Assertions/Warnings]): <ref>[https://github.com/NixOS/nixpkgs/blob/nixos-22.11/nixos/doc/manual/development/assertions.section.md; Nixpkgs/docs: Assertions]</ref>		The NixOS module system again wraps these library functions and makes them available via module options (see [https://nixos.org/manual/nixos/stable/index.html#sec-assertions-warnings NixOS manual: Assertions/Warnings]): <ref>[https://github.com/NixOS/nixpkgs/blob/nixos-22.11/nixos/doc/manual/development/assertions.section.md Nixpkgs/docs: Assertions]</ref>

	* <code>config.warnings = [];</code>		* <code>config.warnings = [];</code>
	* <code>config.assertions = [];</code>		* <code>config.assertions = [];</code>

	An example for a debugging facility in NixOS is running [https://nixos.org/manual/nixos/stable/index.html#sec-running-nixos-tests-interactively; NixOS tests interactively].		An example for a debugging facility in NixOS is running [https://nixos.org/manual/nixos/stable/index.html#sec-running-nixos-tests-interactively NixOS tests interactively].

	== Debugging ==		== Debugging ==

imported>Pogobanane: fix layouting

2023-05-04T13:37:54Z

fix layouting

← Older revision		Revision as of 13:37, 4 May 2023
Line 9:		Line 9:
	== Nix ==		== Nix ==

	The nix language has ~~some constructs~~ to help with printing messages.		The nix language has a construct to help with printing messages.

	* '''assert''': throw an error [2]		* '''assert''': throw an error (see [https://nixos.org/manual/nix/stable/language/constructs.html?highlight=assert#assertions; Nix manual: Assertions])

	The nix language ~~already~~ comes with some ~~usefult~~ builtin functions [3]:		The nix language also comes with some related [https://nixos.org/manual/nix/stable/language/builtins.html; builtin functions]:

	* '''throw''': throw an error with a message		* '''throw''': throw an error with a message
	* '''abort''': same as throw, but always stop evaluation		* '''abort''': same as throw, but always stop evaluation
	* '''trace''': print to stderr		* '''trace''': print to stderr
	* '''traceVerbose''': print, but only when in --trace-verbose mode		* '''traceVerbose''': print, but only when in <code>--trace-verbose</code> mode
	* '''break''': breakpoint when in --debugger mode		* '''break''': breakpoint when in <code>--debugger</code> mode
	* '''tryEval''': catch throws and asserts		* '''tryEval''': catch throws and asserts

	Commonly, assert is combined with throw to generate meaningful error messages: assert condition \|\| throw "message"; This pattern is essentially how lib.assertMsg works (see Sec. nixpkgs). [1]		Commonly, assert is combined with throw to generate meaningful error messages: <code>assert condition \|\| throw "message";</code>. This pattern is essentially how <code>lib.assertMsg</code> works (see Sec. nixpkgs). <ref>[https://github.com/NixOS/nixpkgs/issues/154292; throw vs assert discussion]</ref>

	== nixpkgs ==		== nixpkgs ==
Line 28:		Line 28:
	There are three main facilities for printing errors and do print debugging in nixpkgs:		There are three main facilities for printing errors and do print debugging in nixpkgs:

	* lib.trivial.* [6]		* lib.trivial.* (see [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-trivial; nixpkgs manual: lib.trivial])
	* lib.throwIf and throwIfNot		** lib.'''throwIf''' and throwIfNot
	* lib.warn, warnIf and warnIfNot		** lib.'''warn''', '''warnIf''' and warnIfNot
	* lib.debug.*: tracing functions with some pretty printing [~~7, 9~~]		* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-debug; lib.'''debug'''.*]: tracing functions with some pretty printing <ref>[http://ryantm.github.io/nixpkgs/functions/library/debug/#sec-functions-library-debug; Nixpkgs/docs: lib.debug]</ref>
	* lib.asserts.*: assert functions ~~[8]~~		* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-asserts; lib.'''asserts'''.*]: assert functions

	These facilities also expose their attributes directly via lib.* (e.g. lib.throwIf).		These facilities also expose their attributes directly via <code>lib.*</code> (e.g. <code>lib.throwIf</code>).

	Nixpkgs also has a debugging facility like nix's break: the breakpointHook ~~(see [12~~]).		Nixpkgs also has a debugging facility like nix's <code>break</code>: the [https://nixos.org/manual/nixpkgs/stable/#breakpointhook; breakpointHook].

	== NixOS ==		== NixOS ==

	The NixOS module system again wraps these library functions and makes them available via module options: [11~~, 10~~]		The NixOS module system again wraps these library functions and makes them available via module options (see [https://nixos.org/manual/nixos/stable/index.html#sec-assertions-warnings; NixOS manual: Assertions/Warnings]): <ref>[https://github.com/NixOS/nixpkgs/blob/nixos-22.11/nixos/doc/manual/development/assertions.section.md; Nixpkgs/docs: Assertions]</ref>

	* config.warnings = [];		* <code>config.warnings = [];</code>
	* config.assertions = [];		* <code>config.assertions = [];</code>

	An example for a debugging facility in NixOS is running NixOS tests interactively ~~(see [13~~]).		An example for a debugging facility in NixOS is running [https://nixos.org/manual/nixos/stable/index.html#sec-running-nixos-tests-interactively; NixOS tests interactively].

	== Debugging ==		== Debugging ==
Line 51:		Line 51:
	<!-- put debugging into a heading for search engine optimisation -->		<!-- put debugging into a heading for search engine optimisation -->

	As mentioned above, you can use break to debug nix code, breakpointHook to debug nix builds and ~~NixOS facilities~~ to debug NixOS tests.		As mentioned above, you can use <code>break</code> to debug nix code, <code>breakpointHook</code> to debug nix builds and interactive tools to debug NixOS tests.

	== ~~See also~~ ==		== References ==

	~~[1] throw vs assert discussion: https://github.com/NixOS/nixpkgs/issues/154292~~
	~~[2] https://nixos.org/manual/nix/stable/language/constructs.html?highlight=assert#assertions~~
	~~[3] https://nixos.org/manual/nix/stable/language/builtins.html~~
	~~[4] https://search.nixos.org/options?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=warnings~~
	~~[5] https://nixos.org/manual/nixpkgs/stable/~~
	~~[6] https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-trivial~~
	~~[7] https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-debug~~
	~~[8] https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-asserts~~
	~~[9] http://ryantm.github.io/nixpkgs/functions/library/debug/#sec-functions-library-debug~~
	~~[10] https://github.com/NixOS/nixpkgs/blob/nixos-22.11/nixos/doc/manual/development/assertions.section.md~~
	~~[11] https://nixos.org/manual/nixos/stable/index.html#sec-assertions-warnings~~
	~~[12] https://nixos.org/manual/nixpkgs/stable/#breakpointhook~~
	~~[13] https://nixos.org/manual/nixos/stable/index.html#sec-running-nixos-tests-interactively~~

imported>Pogobanane at 13:04, 4 May 2023

2023-05-04T13:04:57Z

← Older revision		Revision as of 13:04, 4 May 2023
Line 11:		Line 11:
	The nix language has some constructs to help with printing messages.		The nix language has some constructs to help with printing messages.

	- assert: throw an error [2]		* '''assert''': throw an error [2]

	The nix language already comes with some usefult builtin functions [3]:		The nix language already comes with some usefult builtin functions [3]:

	- throw: throw an error with a message		* '''throw''': throw an error with a message
	- abort: same as throw, but always stop evaluation		* '''abort''': same as throw, but always stop evaluation
	- trace: print to stderr		* '''trace''': print to stderr
	- traceVerbose: print, but only when in --trace-verbose mode		* '''traceVerbose''': print, but only when in --trace-verbose mode
	- break: breakpoint when in --debugger mode		* '''break''': breakpoint when in --debugger mode
	- tryEval: catch throws and asserts		* '''tryEval''': catch throws and asserts

	Commonly, assert is combined with throw to generate meaningful error messages: assert condition \|\| throw "message"; This pattern is essentially how lib.assertMsg works (see Sec. nixpkgs). [1]		Commonly, assert is combined with throw to generate meaningful error messages: assert condition \|\| throw "message"; This pattern is essentially how lib.assertMsg works (see Sec. nixpkgs). [1]
Line 28:		Line 28:
	There are three main facilities for printing errors and do print debugging in nixpkgs:		There are three main facilities for printing errors and do print debugging in nixpkgs:

	- lib.trivial.* [6]		* lib.trivial.* [6]
	- lib.throwIf and throwIfNot		* lib.throwIf and throwIfNot
	- lib.warn, warnIf and warnIfNot		* lib.warn, warnIf and warnIfNot
	- lib.debug.*: tracing functions with some pretty printing [7, 9]		* lib.debug.*: tracing functions with some pretty printing [7, 9]
	- lib.asserts.*: assert functions [8]		* lib.asserts.*: assert functions [8]

	These facilities also expose their attributes directly via lib.* (e.g. lib.throwIf).		These facilities also expose their attributes directly via lib.* (e.g. lib.throwIf).
Line 42:		Line 42:
	The NixOS module system again wraps these library functions and makes them available via module options: [11, 10]		The NixOS module system again wraps these library functions and makes them available via module options: [11, 10]

	- config.warnings = [];		* config.warnings = [];
	- config.assertions = [];		* config.assertions = [];

	An example for a debugging facility in NixOS is running NixOS tests interactively (see [13]).		An example for a debugging facility in NixOS is running NixOS tests interactively (see [13]).