addErrorContext

lib.addErrorContext

Primop

Docs pulled from | This Revision | 1 day ago

Contribute

Enhance the ecosystem with your expertise! Contribute to fill the gaps in documentation. Your input can make a difference.

Write API documentation for this function
Learn how to write documentation
Improve position tracking
Contribute to Noogle

Nix manual

Takes 2 arguments

Evaluate context, which can be coerced to a string, and append it to any error or stack traces displayed while evaluating value. Then return value.

This function is useful for providing helpful context in complex Nix expressions when the evaluation of value fails. The additional context is applied when evaluating value itself fails, not when attributes or elements of value are evaluated.

For example, the module system from nixpkgs uses this to show the relevant information about the options that were evaluating when an error occurs.

nix-repl> addErrorContext "while evaluating foo" (throw "bar")
error:
       … while evaluating foo

       … while calling the 'throw' builtin
         at «string»:1:56:
            1| with builtins; addErrorContext "while evaluating foo" (throw "bar")
             |                                                        ^

       error: bar

Noogle detected

Aliases

Detected Type

addErrorContext :: String -> a -> a

Implementation

This function is implemented in c++ and is part of the native nix runtime.

src/libexpr/primops.cc:1019

static void prim_addErrorContext(EvalState & state, const PosIdx pos, Value ** args, Value & v)
{
    try {
        state.forceValue(*args[1], pos);
        v = *args[1];
    } catch (Error & e) {
        NixStringContext context;
        auto message = state
                           .coerceToString(
                               pos,
                               *args[0],
                               context,
                               "while evaluating the error message passed to builtins.addErrorContext",
                               false,
                               false)
                           .toOwned();
        e.addTrace(nullptr, HintFmt(message), TracePrint::Always);
        throw;
    }
}

Implementation

The following is the current implementation of this function.

addErrorContext