Troubleshooting

This page collects common installation and runtime problems and their solutions. It was assembled from real installation notes on macOS (Python 3.11, Homebrew).

Installation problems 

seasenselib / pyproj build failures

seasenselib (the raw-file reader, installed automatically with oceanarray) and its dependency pyproj occasionally fail to build from source on some platforms or pip versions.

If pyproj fails to install, force a pre-built binary wheel, then re-run the install:

pip install --upgrade \
    --force-reinstall \
    --no-cache-dir \
    --only-binary=:all: \
    "pyproj>=3.7.0"

pip install oceanarray

If all else fails, recreate the virtual environment with Python 3.11 exactly (python3.11 -m venv venv) and start from scratch.

Environment problems 

Commands not found after closing the terminal

The virtual environment must be activated in every new terminal session. If you use a venv:

source venv/bin/activate        # macOS / Linux
# venv\Scripts\activate         # Windows

If you use conda:

conda activate oceanarray

If you also use a local shell script to set DATA_BASE or similar environment variables, source that too before running oceanarray commands:

source shlocal/run_mooring.sh   # example — path will differ

Runtime problems 

`oceanarray` prints no output / exits silently

Check that the --proc-dir path exists and that the mooring YAML is present at {proc_dir}/{mooring_name}/{mooring_name}.mooring.yaml. Run with --verbose or -v for more detail.

Stage 1 fails with “no reader found”

seasenselib is not installed, or the file_type: field in the mooring YAML does not match a recognised reader. Run oceanarray list to see accepted file_type strings.

Stage 3 velocity shows all NaN / coordinate_system is BEAM

For Nortek Aquadopps the BEAM→ENU transformation requires a transformation matrix parsed from the .hdr file. If the .hdr file was not found at stage 1, coordinate_system is stored as "BEAM" and stage 3 skips the rotation. Verify that the .hdr file is in the same directory as the .aqd data file and that the header: field in the mooring YAML points to it.

Getting help 

If none of the above solves your problem:

Open an issue at https://github.com/ocean-uhh/oceanarray/issues and include the full traceback and the output of oceanarray --version.
Check that your branch is up to date: git pull.

Troubleshooting

Installation problems

seasenselib / pyproj build failures

Environment problems