FAQ
The FAQ is organised into sections. Some sections are more like Frequently Encountered Issues (FEI), but we list them all on this page so it's easy to search for a solution to your problem.

Symptoms

Error
If you are seeing an error code (E_XXX), then you should look it up here first (the description there may direct you to this page).
Warning
If you get a message printed to your console (shell or Matlab), but BRAHMS seems to behave correctly (including completing brahms_test all without raising an error), this amounts to a warning. These are listed in a separate section, below.
Abort
If BRAHMS fails without reporting an error (i.e. you don't see an E_XXX message, but you don't get any results), this is probably due to an "abort". This is also known as a segmentation fault or an illegal operation, and will be reported by a dialog box (Windows) or with the text "abort" at the prompt (Linux). The Matlab bindings may also detect and report an abort.

General

What does E_XXX mean?
See the errors page here. If it isn't there, contact the developers and ask them to add it.

Installation

This section covers installation problems that prevent you from running the test suite. If brahms_test all completes successfully on your installation, your problem is not addressed in this section.

brahms_test fails with a message like "E_EXECUTION_PARAMETERS: file not found "~/SystemML/BRAHMS/brahms.xml""
On some *nix systems, using a tilde "~" in SYSTEMML_INSTALL_PATH is not supported. Instead, indicate your home path explicitly.
Why do I get E_FAILED_START_MATLAB_ENGINE or an abort when I try to run brahms_test language m?
Unfortunately, there seem to be a lot of ways that the Matlab Engine can be imperfectly installed. As far as we know these are not problems with BRAHMS - please let us know if you know otherwise.
The Matlab Engine will not start on Linux (also OSX?) unless you have csh installed (documented here). On Debian-like systems (e.g. Ubuntu) you can run sudo apt-get install csh to make sure it is installed.
On Linux, and the like, the Matlab Engine will not start unless it is on the machine path. You may see a message, something like "matlab is not on the path". Fix this by editing your .bashrc to add the line
export PATH=$PATH:$MATLABROOT/bin
where $MATLABROOT is the path to your Matlab installation. You may need to restart your machine.
On Windows, the Matlab Engine may fail to start if it is not "registered as a COM server" (documented here). To ensure that it is, run matlab -regserver from the shell in the Matlab bin folder (or run !matlab -regserver from within Matlab).
If you are using Matlab version R14SP3 or earlier on Linux, the Matlab Engine may not start because the bindings are built for R2007a and later. Either upgrade your version of Matlab, or build the Matlab bindings yourself against your version of Matlab (you can obtain the BRAHMS source code from SourceForge).
If you get a message like either of these
GCC_x.x not found
GLIBCXX_x.x.x not found
you are very likely suffering from GregBug, which is not BRAHMS-related (though only we call it GregBug, afaik). Matlab may try to load the libraries supplied with it, rather than those installed on your system. The fix is to hide Matlab's supplied libraries (you may need root privileges). See GregBug for details of how to do this.
If you get the above messages, and the fix at GregBug doesn't solve it, you may be suffering from double-jeopardy GregBug. Matlab secretly changes LD_LIBRARY_PATH on startup to point to the MATLAB version of GLIBC++, so that GLIBC++ 3.4.9 can no longer be found, even if you have applied the GregBug fix. The solution is to modify matlab/bin/.matlab7rc.sh so that "LDPATH_PREFIX" contains the path to the version of GLIB installed with your compiler, then this is found (even before the matlab-supplied library). For non-root users, simply copy the said file to your home directory and edit it there. The line you are looking for reads (originally) LDPATH_PREFIX='', but there are several of these. You need to edit the one in the case statement for your architecture: you can identify this by finding the line like glnx86) but for your architecture. "glnx86" is Gnu/Linux x86; "glnxi64" is (I think) Gnu/Linux Itanium 64-bit. As to the path you need to insert, you need to find a path on your machine which holds the file "libstdc++.so.6" (probably a symlink). On the Ubuntu Gutsy I just installed, this is simply enough at /usr/lib.
If you get an abort, you may be suffering from the run-time version of GregBug (this is when the wrong libraries link and load, but then fail when calls are made into them). Try applying the fix detailed at GregBug, and please let us know if it fixes it.
Under Linux, you may see aborts where you expect to see error messages (try running brahms_test except, which should just raise an error). This may well be caused by linking to the wrong version of the C/C++ runtime libraries, which in turn may have its roots in GregBug, if you are running through Matlab. Treat as GregBug.
If you see the message
I18N Runtime Error:
	Invalid return value for stat detected while processing $(MATLAB)/bin/$(ARCH).
you may be encountering an issue we have seen before on Linux machines. The matlab engine will generally not start if Matlab is not on the path (see above), but it may try and start and fail (with this message) if you happen to be in the Matlab bin directory when you launch it. The solution is (a) to move out of the Matlab bin directory, and (b) make sure the Matlab bin directory is on your machine path (see above). This condition may also generate an abort.
If your system runs fine through Matlab, but fails to start the Matlab Engine if run from the shell, or brahms --WALK fails at the shell, you may see messages like these:
error while loading shared libraries: libeng.so
Either run your system through Matlab (bit rubbish), or set your loader path to include the path to the Matlab library folder. Edit your .bashrc file to augment LD_LIBRARY_PATH to include your Matlab library folder (the path that contains the file libeng.so).
brahms_test all fails at source.m
The first MPI test has failed - if you don't have, or don't intend to use, MPI for inter-process communications (you would know if you were going to use it), then you can ignore this. Otherwise, you have a problem with your MPI installation, or a problem with how BRAHMS is trying to use it.

In Matlab (using 995)

Why does <insert crap browser> open my blue links from the Matlab console?
See the Execution Parameter OpenURL.
Why do I get "File does not exist" in BRAHMS Manager, when selecting a directory?
There is a bug> in the Linux version of Matlab R14SP2, which will manifest in this way. Upgrading to SP3, or a later Matlab release, will resolve the problem. If that route is not available, other workarounds are detailed on this page. Failing that, you can control your environment without using the BRAHMS Manager. See the documentation for Execution Parameters, or type help brahms_utils at the Matlab prompt. For example, to set your WorkingDirectory, use the syntax brahms_utils sep user WorkingDirectory 'my/working/dir'.

Scary Warning Messages

This section lists warning messages you may see that do not affect behaviour. Some answers include suggestions for how to fix them.
What does "Cannot convert string ... to type FontStruct" mean?
This is because NX uses two font servers, one local and one remote, and the local one is not in sync with the remote one. It causes no harm, other than the BRAHMS GUI will not appear quite as intended (the default system font will be used). If you want to fix the problem, we think the easiest solution is to copy the remote font directory over to your local machine (see this). Alternatively, set ShowGUI to false (e.g. at the command-line using --par-ShowGUI=0).
What does "I18N Runtime Warning ..." mean?
Harmless, but details of how to hide this warning are here.
What does "Warning: Handle array initialization failed. ..." mean?
This warning is probably harmless, though it seems intutive given the text that it may cause trouble if you are trying to use matlab handle graphics (TM). However, I have never yet seen these warnings when running a system, only when walking the namespace (where you get engOpen() calls closely following engClose() calls), so it probably won't come up. The closed conversation with MathWorks is here.
What does "Locking assertion failure.... Backtrace..." mean?
This is not BRAHMS-related, and is reported, commonly, on Ubuntu with R2007a, but may occur elsewhere. Seems to be harmless, but see this for the fix. Summary is: ensure package sun-java6-jre is installed, then edit script at $MATLABROOT/bin/matlab and add the first line
export MATLAB_JAVA=/usr/lib/jvm/java-6-sun/jre
(though check the path to the JRE for your system).
What does "GCC_x.x not found" or "GLIBCXX_x.x.x not found" mean?
This is not a harmless warning; search this page for "GregBug".

Native Development

I'm getting an abort - is it my Process, or BRAHMS? When is it happening?
The Structured Log is invaluable for debugging parallel computing problems, but it is less useful for debugging aborts, since it is left unfinished and is not valid XML, so can only be read in a text editor. To generate a full text-only log, run your system from the shell with option --dd and without option --logfmt-xml. Look for what was done just before the abort - if it reads P->service(t), P is very likely causing the abort.
It is also strongly recommended that you run with the option --nothreads, since then you will not get confusion between messages from different threads. If your process is causing the abort, the last thing you see will be something like myprocess->service(t), where t is the base samples when the abort occurred. t will most often be zero, since a process will often abort on the first call if it is going to abort at all. If using --nothreads gets rid of the abort, you are probably facing a thread-safety issue: consider whether multiple instances of your process are confusing each other.
If you get an abort whilst loading a module (i.e. immediately after a message like "loading module M"), you may be seeing a stack overflow, due to very large static variables being placed on the stack. Since it's happening at load-time, these are likely to be global variables in your module. Use the heap for these variables, instead.
If you get an abort following EVENT_MODULE_DESTROY, or in the post-amble messages following the first call to this Event, you may be doing something naughty in your destructor (problems of this sort sometimes do not cause an abort immediately, so often the abort does not immediately follow the call to the event). Try not freeing anything in your destructor, to see if it goes away. Note that destructors will be called on all member objects of your class, as well, when your class is destroyed - this is easy to miss.
Attach a debugger. See this page.
What does it mean that my abort goes away when I turn on full logging (--dd)?
Probably that it is a thread-safety bug, and that full logging slows things down just enough to prevent it from manifesting. Are you using threads, explicitly or implicitly? Or process-shared memory? Are there global variables in your module that are accessed by all instances of your Component? Are you using Operating System services, particularly GUI services? If so, your problem probably lies in thread-safety. If not, you may have found a bug in BRAHMS - please try and make sure before reporting it.
The process I've written works fine in my test system - why does it abort when connected in some other system?
EVENT_INIT_CONNECT is fired on processes multiple times in general, with more inputs available on each subsequent call. In a simple system, your Process may receive only one EVENT_CONNECT call, with all its inputs available. Once connected in a larger system, it may receive EVENT_INIT_CONNECT with some inputs not available. If you have made an incautious assumption that a Data object is non-NULL, this may be when you find out (this is an easy mistake to make). Correct the logic in your EVENT_INIT_CONNECT implementation, and make sure Data is Due before you use it. See F_NEEDS_ALL_INPUTS, F_FIRST_CALL and F_LAST_CALL.
The process I've written work fine in Solo - why does it abort when I start using Concerto?
See the above answer - when you switch to Concerto, your system may be initialised in a completely different order.

Matlab Development (1258)

How do I debug a Matlab process?
You can't. I'm not sure if you're allowed to debug within the Matlab engine at all - certainly, if you use a keyboard command, the engine ignores it with
Warning: Keyboard command not available when using MATLAB as Engine
If you try to set a debug point in an engine you've left open, then you get a hang (Win32, Matlab R14SP3, BRAHMS Beta1 RC7) that can only be broken the hard way. I'm not sure if you get debugging capability at all in the Engine. If you have more information, and certainly if you have any debugging success, let us know.

Performance

Why does my system not run faster on a machine with multiple cores/processors?
If you turn off multi-threading (set MaxThreadCount to 1, or pass --nothreads), your system will be run in a single thread, and cannot take advantage of multiple cores/processors.
If all of your processes are authored in a non-thread-safe language (such as Matlab or Python), they cannot be run in parallel. If future releases of these engines are thread-safe, BRAHMS will be updated to take advantage. In the meantime, you can still get a speed-up by using Concerto.

Possible Future Issues

Why does BRAHMS abort when more than one copy is running on my machine?
If using processes that set F_NO_CONCURRENCY (for instance, any authored in Matlab), we may run into problems if they are called concurrently in different //voices// as well as if they are called concurrently in different threads. For example, if a bunch of people are using BRAHMS on the same machine, perhaps on different processors, executing entirely unrelated jobs but through the same Matlab engine (or Matlab engine libraries), this could cause random seg faults or data corruption. If you think you are seeing problems of this sort, please get in touch and help us to identify and solve them.