Windows: h5py==3.16.0 crashes runtime path; downgrading to h5py==3.15.1 lets Matterix run and workflow progress

[EEPPRR333]

Title

Windows: h5py==3.16.0 crashes runtime path; downgrading to h5py==3.15.1 lets Matterix run and workflow progress

Body

Hi, thanks for open-sourcing Matterix.

I am trying to reproduce Matterix on Windows 11 following the repository README and Isaac Lab installation instructions. I want to report a Windows-specific issue and a workaround that appears to make the project run.

Environment

• OS: Windows 11 x64
• GPU: NVIDIA GeForce RTX 4060 Laptop GPU (8 GB VRAM)
• RAM: 16 GB
• Python: 3.11 (conda environment)
• PyTorch: 2.7.0+cu128
• Torchvision: 0.22.0+cu128
• Isaac Lab: 2.3.0
• Isaac Sim: 5.1.0.0

Repository setup

I followed the README / Isaac Lab installation path:

conda create -n matterix2 python=3.11
conda activate matterix2

pip install -U torch==2.7.0 torchvision==0.22.0 --index-url https://download.pytorch.org/whl/cu128
pip install "isaaclab[isaacsim,all]==2.3.0" --extra-index-url https://pypi.nvidia.com

git clone --recurse-submodules https://github.com/ac-rad/Matterix.git
cd Matterix
git lfs install
git submodule foreach "git lfs pull"

On PowerShell, I could not use:

python -m pip install -e source/*

so I installed the editable packages one by one:

python -m pip install -e .\source\matterix_sm
python -m pip install -e .\source\matterix_assets
python -m pip install -e .\source\matterix_tasks
python -m pip install -e .\source\matterix

I also set:

$env:MATTERIX_PATH="E:\matterix-work\Matterix"

What worked

The following all worked:

• import isaaclab
• import h5py
• import isaaclab; import h5py
• minimal AppLauncher(headless=True)
• import isaaclab_tasks
• import matterix_tasks
• python scripts/list_envs.py
• python scripts/list_workflows.py --task Matterix-Test-Beaker-Lift-Franka-v1

I was able to list:

• Matterix-Test-Beakers-Franka-v1
• Matterix-Test-Particle-systems-Franka-v1
• Matterix-Test-Beaker-Lift-Franka-v1

and the workflow:

• pickup_beaker

Problem with h5py 3.16.0

Initially, I had:

python -c "import h5py; print(h5py.__version__)"
# 3.16.0

With h5py==3.16.0, both of the following failed during the full runtime path:

python scripts/zero_agent.py --task Matterix-Test-Beakers-Franka-v1 --num_envs 1
python scripts/run_workflow.py --task Matterix-Test-Beaker-Lift-Franka-v1 --workflow pickup_beaker --num_envs 1

The crash path consistently went through:

• isaaclab_tasks
• isaaclab.utils.datasets
• HDF5DatasetFileHandler
• h5py

and produced:

Windows fatal exception: code 0xc0000139

Workaround that made it run

I downgraded h5py:

pip uninstall -y h5py
pip install h5py==3.15.1 --no-cache-dir

Then:

python -c "import h5py; print(h5py.__version__)"
# 3.15.1

After this downgrade:

1) zero_agent.py runs successfully

python scripts/zero_agent.py --task Matterix-Test-Beakers-Franka-v1 --num_envs 1

It creates the environment, starts simulation, and prints repeated observations.

2) run_workflow.py also runs and the workflow progresses

python scripts/run_workflow.py --task Matterix-Test-Beaker-Lift-Franka-v1 --workflow pickup_beaker --num_envs 1

This now successfully:

• initializes the environment
• starts simulation
• initializes the state machine
• enters Episode 1
• starts executing the workflow

The action sequence shown is:

1. OpenGripper
2. MoveToFrame
3. MoveToFrame
4. CloseGripper
5. MoveRelative

At first it appeared to stay at:

[0/5] OpenGripper [running]

but after continued observation the workflow does progress, so it is not a hard freeze.

Remaining warning

While the workflow is running, I still see this PhysX warning/error:

Collision rest offset must be lesser then contact offset
prim: /World/envs/env_0/RigidObjects_Labware_beaker/Scene/Beaker_500mL

So my current understanding is:

• h5py==3.16.0 appears to break the Windows runtime path
• h5py==3.15.1 is an effective workaround on my machine
• after that workaround, Matterix can run on Windows and the workflow can progress
• there may still be a remaining beaker physics / collision configuration issue

Questions

1. Is h5py==3.16.0 currently known to be problematic with Matterix / Isaac Lab on Windows?
2. Would it make sense to pin h5py==3.15.1 on Windows for now?
3. Is the beaker collision offset warning expected, or does it indicate a configuration issue in the test task / asset?

Thanks — I’m happy to provide more logs if useful.

Suggested logs to attach

1) Key lines from the h5py 3.16.0 crash

Attach only the relevant lines showing:

• isaaclab.utils.datasets
• HDF5DatasetFileHandler
• h5py
• 0xc0000139

2) A few successful lines from zero_agent.py after downgrading to h5py 3.15.1

For example:

• Environment created successfully
• Starting the simulation
• one or two observation lines

3) A few lines from run_workflow.py

For example:

• STATE MACHINE ACTION SEQUENCE INITIALIZED
• [0/5] OpenGripper [running]
• later lines showing that the workflow progresses