Errors

Errors in NPL come in two categories: compile time errors starting with E, and runtime errors starting with R. Below all NPL runtime errors are explained.

Runtime errors

All runtime errors start with R, followed by the error code number listed below.

Code	Message	Description
0	Unknown	An error that is not specifically handled.
1	'ARGUMENT' must be of type 'EXPECTED', but must be of type 'ACTUAL'	The type of provided argument does not match the expected type.
2	Unknown state 'STATE'	Attempt transition to an unknown protocol state.
3	No such protocol 'ID'	A protocol with this identifier cannot be found.
4	No such prototype 'PROTOTYPE'	Attempt to load a prototype that cannot be found.
5	Unknown action 'ACTION' for protocol 'PROTOCOL'	Attempt to invoke an action that is not defined in this protocol.
6	Undefined variable 'NAME'	Attempt to reference a variable that is not defined.
7	Undefined property 'NAME' on 'TYPE'	Attempt to load an undefined struct, protocol or state property.
8	Protocol 'ID' has changed during transaction (actual version differs from expected version)	The protocol has been modified by another transaction and is no longer of the specified version.
9	Index 'INDEX' exceeds collection size 'SIZE'	Specified index is larger than the size of the underlying collection.
10	Cannot access property 'NAME' on a receiver of type 'TYPE'	Attempt to access a property on something that has no properties.
11	Attempt to set unknown field 'NAME' on struct 'TYPE'	Attempt to set an unknown field on a struct (using with).
12	Illegal attempt to set property 'NAME' on target of type 'TYPE'	Attempt to set a property on something that is not a protocol.
13	Illegal protocol state: current state 'STATE' is not one of ...	Attempt to invoke an action while the protocol is not in one of the allowed states.
14	Assertion 'REQUIRE' failed ('REQUIRE_ID')	Require expression evaluated to false.
15	Assertion must be boolean, but is of type 'TYPE'	Require expression does not evaluate to a boolean value.
16	Invalid data uri input: 'INPUT'	Supplied argument does not constitute a valid data URI.
17	'PARTIES' illegally tried to invoke 'ACTION' on 'PROTOCOL'	Attempt to invoke an action while lacking permission.
18	Action is only valid starting 'DATETIME'	The action was invoked before its after clause comes into effect.
19	Action was only valid until 'DATETIME'	The action was invoked after it has expired.
20	Time constraint must be of type DateTime, but is of type 'TYPE'	Time constraint is not of type DateTime.
21	Illegal attempt to transition out of final state 'STATE'	It is not allowed to transition out of a final state.
22	Notify must target a notification, but is of type 'TYPE'	Notify statement targets something that is not a notification.
23	Attempt to call type 'TYPE'	Attempt to invoke something that is not a function.
24	Argument error, expected 'EXPECTED' parties, but got 'ACTUAL'	The wrong number of parties were provided.
25	Illegal operation 'OP' for operand ...	Operator and operand(s) are incompatible.
26	'METHOD' incompatible with argument(s) 'ARGUMENTS'	Provided arguments are of the wrong type.
27	Optional is empty	Attempt to obtain a value from an empty optional.
28	Value 'VALUE' is not an integer	Expected number to be an integer (e.g., for indices), but it was not.
29	Lambda for 'NAME' must be of type 'EXPECTED', but is of type 'ACTUAL'	Supplied lambda does not match the expected type signature.
30	Argument error, expected 'EXPECTED' arguments but got 'ACTUAL'	Incorrect number of arguments were supplied.
31	Argument error, expected ... arguments, but got ...	Incorrect number of supplied fields when creating a struct.
32	No such type 'TYPE'	Attempt to resolve a non-existent type from a reference.
33	Got 'ACTUAL' type parameters	Incorrect number of type parameters.
34	Argument 'INDEX' does not evaluate to a party	Supplied argument is not a party of the protocol.
35	'ARGUMENT' must be of type 'EXPECTED', but 'NAME' is of type 'ACTUAL'	Actual type parameter was not of the expected type.
36	Unknown variant 'NAME' for enum 'TYPE'	The enum variant is not known.
37	Could not resolve party from 'CLAIMS' to invoke 'ACTION' on 'PROTOCOL'	The specified party could not be resolved.
38	Expected action to fail with 'R_ID' but failed with wrong code 'R_ID'	The test was expected to fail, but did not fail as it was expected.
39	Cannot access 'NAME', it has no @api annotation	An @api annotation could be missing.
40	Invalid caller 'CALLER' (parties 'PARTIES')	The caller does not match the parties of the called action.
41	No security context found	The caller can not be authorised. Likely an IAM (e.g. Keycloak) configuration error.
42	Access token has no designated parties	If you experience this, you have got the answer to everything.
43	Source compilation error	The snippet evaluated is not valid NPL.
44	No debugger service session with 'ID'	🦠  Attempt to connect to a debugger session unknown to the engine.
45	No environment service session with 'ID'	🦠  Attempt to connect to a seeded environment unknown to the engine.
46	No such function 'FUNCTION'	Attempt to execute or debug a function that doesn't exist.
47	Attempt overwrite existing prototype 'PROTOTYPE'	A prototype is provisioned which would overwrite an existing prototype.
48	Attempt to rewind engine clock from 'DATETIME' to 'DATETIME'	🦠  Attempt to rewind the clock from within the sandbox.
49	Attempt to illegally access 'PROTOCOL', these protocols have no parties/observers in common	The calling and called protocols have no parties/observers in common.
50	List argument 'LIST' must have size 'EXPECTED', but has size 'ACTUAL'	List must be of expected size (zipOrFail).
51	Variant 'VARIANT' not found for 'TYPE'	Unknown enum variant.
52	Invalid generic struct 'PROTOTYPE' for 'TYPE'	Invalid generic struct.
53	Claims should not be empty	Provided claims should not be empty.
54	Can't find substitute for 'TYPE'; verify that the code structure/integrity is valid	Type inference issues.
55	Protocol 'ID' does not contain field 'FIELD'	While anonymizing, provided field does not exist for the given protocol.
56	Argument value provided is not a map type, but instead 'TYPE'	While anonymizing, arguments provided is not a map.
57	Protocol 'ID' field 'FIELD' of type 'EXPECTED' does not match the proposed value type 'ACTUAL'	While anonymizing, arguments field type provided is not correct.
58	An unrecoverable error has occurred: 'ERROR'	Unrecoverable error occurred which should stop the program execution.

Errors marked 🦠  are specific to the sandbox.

Stack traces

Runtime errors inform the user what has gone wrong, but not where it has gone wrong. Detailed stack traces are provided to show the path that led to the error.

Consider the following code, wrapped in a file test.npl, in which a require that always fails is present on Foo4's go permission.

protocol[p] Foo1() {
    init {
        Foo2[p]().go[p]();
    };
};

protocol[p] Foo2() {
    function goAgain() -> {
        Foo3[p]().go[p]();
    };

    permission[p] go() {
        goAgain();
    };
};

protocol[p] Foo3() {
    permission[p] go() {
        Foo4[p]().go[p]();
    };
};

protocol[p] Foo4() {
    permission[p] go() {
        require(false, "Imminent failure");
    };
};

Attempting to create an instance of Foo1 produces the stack trace

Error caused by 'R14: Assertion 'Imminent failure' failed ('/test.npl/Foo4/go/Imminent failure')'
    at /test.npl/Foo4/go#963fc0e6-0f43-48c4-a57c-f04a18cec956(test.npl:25)
    at /test.npl/Foo3/go#309899c6-e752-4756-ab9c-111ce9e4b3b4(test.npl:19)
    at /test.npl/Foo2/goAgain#bdb9a7d1-6bb7-409b-8e46-09ff4bd91731(test.npl:9)
    at /test.npl/Foo2/go#bdb9a7d1-6bb7-409b-8e46-09ff4bd91731(test.npl:13)
    at /test.npl/Foo1<creation>#d68dff7e-36f8-4811-932a-6f9484989082(test.npl:3)

The error code indeed signals a failing clause, and displays the message "Imminent failure". Each subsequent line traces the path and corresponds to the format

at <protocolDefinition><optionalLocation>#<protocolId>(<fileName>:<lineNumber>)

At the bottom the entry point is shown to be the <creation> of /test.npl/Foo1. For go and goAgain on Foo2, the stack trace shows the same protocol ID bdb9a7d1-6bb7-409b-8e46-09ff4bd91731, signaling that this is therefore the same protocol instance.

Built-ins do not have an NPL source, and show up in stack traces with their short function names and with source file <builtin>. For example, creating an instance of Foo5 given

protocol[p] Foo5() {
    init {
        optionalOf<Number>().getOrFail();
    };
};

leads to the stack trace

Error caused by 'R27: Optional is empty - expected `Some` but found `None`'
at //lang/core/Optional<T>::lang/core/getOrFail(<builtin>:0)
at /errors/Foo5<creation>#f9140222-b196-4282-9638-579cadefd1d4(/errors/errors.npl:36)