Skip to content

Troubleshooting Notes

🔵 My output appears to be out of order: errors are not printed exactly when they occur

If you redirect stdout and stderr to a file, you may notice that stderr lines are out-of-order with respect to the stdout lines; for example: 

myAnalysisProgram                    # stdout and stderr print when they happen; ordering appears correct

myAnalysisProgram |& tee output.txt  # stderr prints when it happens, but stdout only prints when its buffer is full;
                                     # ordering appears mixed up
To redirect output to a file with the ordering preserved, run your executable with stdout unbuffered: 
stdbuf -o0 myAnalysisProgram |& tee output.txt

NOTE: stdbuf on macOS may be installed as gstdbuf, from the Homebrew package coreutils.

🔵 I got a crash, but the stack trace (or debugger) is not telling me exactly where

Enable debugging symbols by setting the Iguana build option buildtype to 'debug', then rebuild. Assuming you're in your build directory, run: 

meson configure -D buildtype=debug
Then rebuild (meson compile and/or meson install).

Remember to revert this change and rebuild/re-install, so that Iguana runs with full optimization when you are processing large data sets (-D buildtype=release).

🔵 I got some error about 'chameleon', or an error in some 'chameleon' file that I can't find

Chameleon is a code generator to automatically create iguana bindings for programming languages other than C++. All generated code is produced in your build directory. If you have issues with Chameleon, either:

  • an Action.yaml file is not correct
  • something is wrong with chameleon

In either case, open an issue or contact the maintainers.

🔵 The CI reports an error 'xcheck failed' or 'Algorithm cross check test (xcheckalgo) failed'

Running the algorithm single-threaded produces results that do not agree with those from running the algorithm multithreaded; there is likely a data race. Check the thread sanitizer CI job to see if it detected any data race. If not, one known undetectable data race is calling hipo::bank::rowlist::filter with a callback function with the wrong signature: 

// this is okay: the `bank` parameter is passed by lvalue reference
my_bank.getMutableRowList().filter([](auto& bank, auto row) { /* ... */ });

// this is NOT okay: the `bank` parameter is passed by value (no ampersand `&`),
// which can lead to a (rare) data race
my_bank.getMutableRowList().filter([](auto bank, auto row) { /* ... */ });