Overview

BRAHMS errors and warning messages are tagged with a code. Looking up that code on this page will give you more information about the context, conditions and nature of the error, and advise you on how to prevent it. If you encounter an error that is not described here, please let the developers know.

What you'll see

You can run the BRAHMS executable directly, or through the Matlab Invocation Bindings. In each case, you'll get much the same output when an error occurs. Below, we show the output when we run brahms_test except directly, from the shell. If you want to see what this will look like through the Matlab bindings, this is shown at the bottom of this page.

Component Errors

This error was generated by running brahms_test except in Matlab, though we show here what it looks like when you run this Execution from the shell.

OS Shell Prompt
$ brahms d:\BRAHMS\WorkingDirectory\except-exe.xml E_USER: raising as requested during EVENT_RUN_RESUME whilst firing EVENT_RUN_RESUME on except2 E_USER: raising as requested during EVENT_RUN_RESUME whilst firing EVENT_RUN_RESUME on except3 E_USER: raising as requested during EVENT_RUN_RESUME whilst firing EVENT_RUN_RESUME on except1

The main item here is the E_XXX error code and the accompanying message. In this case it's E_USER, which is the code for errors generated by Components, rather than by the Framework. Next to the E_XXX code is the message the component passed to indicate what actually went wrong. In this case, the client/brahms/test/except Component has done what it was asked to do, and thrown an error during EVENT_RUN_SERVICE.

If you want more information, pass the flag --maxerr to the executable. In this case, underneath the error code and message is a stack of trace information, which tells you where and when the error occurred (see below). In addition, the E_THREAD_ERROR that was used to bring down the execution is shown in full (this is usually hidden, since it is an implementational detail).

OS Shell Prompt
$ brahms d:\BRAHMS\WorkingDirectory\except-exe.xml --maxerr E_USER: raising as requested during EVENT_RUN_RESUME in client_brahms_test_except_0::event() at except.cpp:107 whilst firing EVENT_RUN_RESUME on except3 at thread.cpp:383 caught in thread "W4" caught after 0.0067152 secs (thread time) E_USER: raising as requested during EVENT_RUN_RESUME in client_brahms_test_except_0::event() at except.cpp:107 whilst firing EVENT_RUN_RESUME on except1 at thread.cpp:383 caught in thread "W2" caught after 0.00704481 secs (thread time) E_USER: raising as requested during EVENT_RUN_RESUME in client_brahms_test_except_0::event() at except.cpp:107 whilst firing EVENT_RUN_RESUME on except2 at thread.cpp:383 caught in thread "W3" caught after 0.00692543 secs (thread time) E_THREAD_ERROR: in waitForIdle() at thread.cpp:258 at api-engine.cpp:171 whilst processing "e" caught in thread "C" caught after 0.251311 secs (thread time)

Framework Errors

OS Shell Prompt
$ brahms "d:\BRAHMS\Working Directory\except-exe.lalala" E_INVOCATION: Execution File "d:\BRAHMS\Working Directory\except-exe.lalala" not found whilst processing "u"

Here, we tried more or less the same thing, but we changed the filename from ".xml" to ".lalala", which doesn't exist. Now, the error code is E_INVOCATION, which is not E_USER, so we know it's a Framework error, and we can look it up on this page to find out what it means and what we can do about it. In this case, the additional message "Execution File ... not found" is probably enough to clue us in.

General Error Codes

All E_XXX constants are of type Symbol.

E_ERROR
General framework error (no further information). This error code is returned when the developer hasn't specified any particular code, and should not be encountered. Please report this error if you can make it occur repeatably.
E_USER
This tag accompanies all errors raised by BRAHMS components; the accompanying message should give more information about the error and how to solve it. If the component is supplied with BRAHMS, there may be more information on the documentation page for the component.

Specific Error Codes

All E_XXX constants are of type Symbol.

E_BAD_ARG_COUNT
The call to EVENT_FUNCTION_CALL had the wrong number of arguments (expected argument count returned in event data).
E_BAD_ARG_TYPE
The call to EVENT_FUNCTION_CALL had an argument of the wrong type (offending argument index returned in event data).
E_BAD_ARG_SIZE
The call to EVENT_FUNCTION_CALL had the wrong number of arguments (offending argument index returned in event data).
E_CIRCULAR_REFERENCE
The system you sent for execution could not be executed due to a circular reference in its combined State. This is a technobabble way of saying that you've got a closed loop in your System with all zero-lag links in it. A --> B --> A with zero lag links cannot be computed, because the output of A at time t depends on itself, so BRAHMS will flip out.
E_INVOCATION
There was an error parsing or acting on the invocation parameters (the command line, in a command-line build).
E_COMMS
General communications error (not caused by the user).
E_COMMS_TIMEOUT
A communications timeout occurred.
E_DATAML
DataML read error.
E_DATA_TYPE_UNSUPPORTED
An attempt was made to translate a data object from one context (e.g. language) to another, and the data type was not supported in the target context. You'll get this, for instance, if you try to pass boolean (logical) data as state data into a Python process, since Python does not have a boolean data type.
E_DEADLOCK
The system you sent for execution could not be instantiated due to circular dependencies in parametrization; a Deadlock has occurred. This is caused when the Src of a Link still does not exist when iterative connection has ceased making progress. One possibility is that you have simply specified the Src incorrectly. The other (less obvious) is that there is a circular dependency in your system - process A can't produce output A>out until it sees B>out; process B can't produce output B>out until it sees A>out. You must resolve circular dependencies by deciding which process has to give ground, and modifying the process (or its parameters).
E_EXECUTION_FILE
There was an error parsing the Execution File.
E_EXECUTION_PARAMETERS
Something was wrong with the Execution Parameters (invalid parameter, or parameter mismatch, for instance).
E_FAILED_START_MATLAB_ENGINE
The Matlab bindings were unable to connect to an instance of the Matlab Engine. Either you do not have matlab installed (unlikely, since the bindings loaded in the first place) or there is a problem just with the Matlab Engine. See the FAQ for more information.
E_FAILED_LOAD_MODULE
The OS refused to load the specified module, usually due to a missing dependency (shared library, dll or so); the cause may be confirmed, on Windows, by the error being tagged with "Windows Error 126", in which case you should get a dialog box pop up before the error is raised indicating which dependency was missing. This may happen when trying to load a Component Module. In this case you should check the documentation for that component, and ensure that its dependencies are present (generally, Component modules should not have dependencies, but some, e.g. hardware-interaction modules, necessarily will). This may, alternatively, happen when attempting to load a Component Binding or Communications module, both part of the framework. In this case, you probably need to make sure that whatever the framework module is concerned with is installed - consider Matlab, Python, or MPI, based on the module name. In all cases, the loader must be able to find the required dependencies, which usually means making sure they are on PATH. To debug dependency problems, see lld (Linux, OSX) or depends.exe (Windows).
E_FUNC_NOT_FOUND
The requested function is not offered by this Utility object.
E_INPUT_RATE_MISMATCH
A process that set flag F_INPUTS_SAME_RATE received an input that did not match its sample rate.
E_INSTALLATION
There is a problem with the BRAHMS installation.
E_INTERNAL
Internal error (unintended condition reached - contact developers).
E_INVALID_ARG
One of the arguments passed to the function was invalid.
E_INVALID_HANDLE
The passed object handle was not valid.
E_MATLAB
There was a general error in calling out to Matlab.
E_MEMORY
The system is out of memory.
E_MISMATCH
Something didn't match (examine the call for more details).
E_MPI
General MPI (comms) error.
E_NAMESPACE
The requested component class was not found in any of the namespaces BRAHMS searched. To see what namespace paths BRAHMS searches, try brahms --walk - if the requested component class does not appear in the listing that is produced, you either need to correct your class name (note that Namespace class names are case-sensitive), install the required process, or make sure BRAHMS knows where to find the namespace where the component is installed (see NamespacePath).
E_NO_INSTANCE
A component binding was called to service an event but no object was passed, and that was not valid (internal error).
E_NOT_AVAILABLE
Requested item not currently available.
E_NOT_COMPLIANT
A component did not meet the requirements of the interface (did not correctly service an event).
E_NOT_FOUND
The requested item was not found.
E_NOT_IMPLEMENTED
Requested operation not implemented (that is, hasn't been coded yet, rather than isn't going to be).
E_NOT_SERVICED
Thrown by the framework if a module does not respond to an event that it is required to service.
E_NULL_ARG
One of the arguments passed to the function was NULL (or S_NULL) which was invalid.
E_OS
Operating System returned an error - this could mean that a file was not found, or unreadable, for instance.
E_OUT_OF_ORDER_DELIVERY
This error indicates that messages in an inter-voice data stream arrived out-of-order. Currently, we do not try to re-order them, since we have never encountered this error under normal conditions. If you see this error, please report it.
E_OUTPUT_RATE_MISMATCH
A process that set flag F_OUTPUTS_SAME_RATE generated an output that did not match its sample rate.
E_OVERFLOW
Buffer overflow - provide a larger buffer and try again.
E_PEER_ERROR
Another voice raised an error (this error should never be displayed, since no local error has occurred).
E_PORT_EMPTY
Data was requested from a port, and the port was empty (the Data was not Due).
E_PRIORITY_FAIL
It was not possible to set the requested priority level (either for the BRAHMS process, or for a particular thread). On Windows, this error should not occur. On NIX systems, this error is likely to be caused by an RLIMIT. For more information, see Priority Management.
E_PYTHON
There was a general error in calling out to Python.
E_REALITY_INVERSION
Something impossible has happened.
E_STD
C++ Standard Library Exception (more information in message).
E_SYNC_TIMEOUT
An inter-thread synchronisation timeout occurred (currently, these can't occur, I'm pretty sure).
E_SYSTEM
The System sent for execution was invalid.
E_SYSTEMML
General SystemML Interface failure.
E_SYSTEM_FILE
There was an error parsing the System File.
E_THREAD_ERROR
If one or more worker threads throws an error, this error is thrown by the caller thread, to force the caller thread down. You don't usually see this, but you will see it if you pass the --maxerr flag.
E_THREAD_HUNG
A thread did not send signal C_STILL_ACTIVE for TimeoutThreadHang milliseconds. You can avoid this error by raising the value of TimeoutThreadHang, though generally it indicates a problem with one of the processes in the system (either the process has genuinely hung, or it is not signalling C_STILL_ACTIVE sufficiently often).
E_UNRECOGNISED_EXCEPTION
An exception was caught that could not be identified (if not thrown from user code, contact developers).
E_UNRECOGNISED_INFO_FIELD
A non-native process returned an unrecognised field in response to EVENT_MODULE_INIT. Note that the syntax for servicing EVENT_MODULE_INIT from non-native processes was made consistent with that for native processes at version 0.7, so if you just upgraded to 0.7, your files may be out of date; check the current syntax of the 1258 bindings.
E_UNREPRESENTABLE
If it is not possible in BRAHMS to represent the timing of the execution, this error will be raised. This error comes in three flavours, represented in brackets after the error code, indicating different failures. (sample rate) indicates that one or more sample rates in the System overflows a 64-bit integer (exceeds 264-1). (base rate) indicates that the Base Sample Rate calculated from all System sample rates overflows a 64-bit integer. (stop time) indicates that the execution stop time represented in base samples overflows a 64-bit integer. For more information and a discussion of how to make such a System computable, see Base Clock. NOTE Currently, if the execution stop time exceeds 10 to the 15 an error is thrown, since I haven't got round to writing the code to do the conversion of numbers larger than this from floating-point to UINT64 without loss of precision.
E_UNSUPPORTED_INTERFACE
A component that was loaded required a version of the Component Interface later than that loaded, and could not be run. To use this component, you must install a later version of BRAHMS.
E_VOICE_UNDEFINED
A ((VOICE)) token was used in one of the filenames passed to BRAHMS, but the voice index was not defined when these filenames were needed. Specify the voice explicitly on the command-line, or avoid using those tokens, to fix this error.
E_WRONG_COMPONENT_TYPE
A Component was loaded and instantiated, but turned out to be the wrong type for the purpose it was being loaded. You are most likely to encounter this if you try to add a Process to a system, but accidentally specify a Data or Utility class. Similarly, if you intended to specify a Data or Utility class, and specify a Component of a different type, you will get this error.
E_WRONG_HANDLE_TYPE
The passed handle was of the wrong type.
E_WRONG_INTERFACE
A Port or Set handle passed to the input or output SystemMLInterface object belongs to the other (output or input) interface.
E_WRONG_NEW_HANDLE_TYPE
The handle returned whilst creating the requested new object was of the wrong type.
E_XML_PARSE
XML parse error.
E_XML
General XML Interface failure.
E_ZLIB
Failure whilst calling the compression library, zlib.

What you'll see (Matlab Invocation Bindings)

Note that the blue underlined words are hyperlinks, linking either to the log file for that voice, or to the documentation for the specified error. These links are not available when running from the shell.

Solo

Matlab Console
>> brahms_test except ________________________________________________________________ Voice 1: Log File (Empty) Command: brahms-execute "D:\BRAHMS\wd\except-exe.xml" ... --logfmt-xml --voice-1 --logfile-"D:\BRAHMS\wd\except-log-1.xml" ... --exitfile-"D:\BRAHMS\wd\except-rep-1.xml.exit" E_USER: raising as requested during EVENT_RUN_RESUME whilst firing EVENT_RUN_RESUME on except3 E_USER: raising as requested during EVENT_RUN_RESUME whilst firing EVENT_RUN_RESUME on except1 E_USER: raising as requested during EVENT_RUN_RESUME whilst firing EVENT_RUN_RESUME on except2 ________________________________________________________________ ??? Error using ==> brahms at 262 One or more errors occurred during execution Error in ==> brahms_test>execsys at 2162 [out, rep] = brahms(sys, exe, opt.opts{:}); Error in ==> brahms_test at 1607 [out, rep, expected] = execsys(sys, exe, opt);
Notes
  • You can pass --maxerr, like any command-line switch, through the Matlab bindings, too.

Concerto

Matlab Console
>> brahms_test except.s ________________________________________________________________ Voice 1: Log File (Empty) Command: start /B brahms-execute ... "D:\BRAHMS\wd\except-exe.xml" --logfmt-xml --voice-1 ... --logfile-"D:\BRAHMS\wd\except-log-1.xml" ... --exitfile-"D:\BRAHMS\wd\except-rep-1.xml.exit" E_USER: raising as requested during EVENT_RUN_RESUME whilst firing EVENT_RUN_RESUME on except2 ________________________________________________________________ Voice 2: Log File (Empty) Command: start /B brahms-execute ... "D:\BRAHMS\wd\except-exe.xml" --logfmt-xml --voice-2 ... --logfile-"D:\BRAHMS\wd\except-log-2.xml" ... --exitfile-"D:\BRAHMS\wd\except-rep-2.xml.exit" E_USER: raising as requested during EVENT_RUN_RESUME whilst firing EVENT_RUN_RESUME on except3 E_USER: raising as requested during EVENT_RUN_RESUME whilst firing EVENT_RUN_RESUME on except1 ________________________________________________________________ ??? Error using ==> brahms at 262 One or more errors occurred during execution Error in ==> brahms_test>execsys at 2162 [out, rep] = brahms(sys, exe, opt.opts{:}); Error in ==> brahms_test at 1607 [out, rep, expected] = execsys(sys, exe, opt);

Pre-execution Error

If an error occurs before the usual preamble is completed, you may get a slightly less informative error message. For example, here we show what happens if MPI support is requested, but it is not available.

Matlab Console
>> brahms_test except.m ________________________________________________________________ found exit file without ((VOICE)) set (usually indicates that MPI had not started when the error occurred): E_MPI: insufficient MPI support (MPI_THREAD_MULTIPLE required, MPI_THREAD_SINGLE provided) at protocol-mpi.cpp:212 ________________________________________________________________ ??? Error using ==> brahms at 262 One or more errors occurred during execution Error in ==> brahms_test>execsys at 2162 [out, rep] = brahms(sys, exe, opt.opts{:}); Error in ==> brahms_test at 1607 [out, rep, expected] = execsys(sys, exe, opt);