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);
|