HeteroData silently accepts numpy arrays. Then fails during training with cryptic message

[Gabriel-Kissin]

🐛 Describe the bug

Hi PyG team, thanks for the great package! The other day I spent a good while debugging an issue that I think could be caught much earlier with better error messages.

When creating a HeteroData object from networkx/pandas (I'm guessing this is a fairly common workflow), numpy arrays can accidentally end up as node features instead of torch tensors. PyG silently accepts these numpy arrays, and the error only surfaces deep in model execution with n unhelpful message.

MRE

import numpy as np
import torch
import torch_geometric
from torch_geometric.data import HeteroData
from torch_geometric.nn import SAGEConv, to_hetero
from torch_geometric.transforms import ToUndirected

# Create HeteroData with numpy arrays forgetting to convert to tensor
data = HeteroData()
data['user'].x = np.random.randn(100, 64)  # numpy array, not tensor
data['item'].x = np.random.randn(100, 64)   # numpy array, not tensor
data['user', 'likes', 'item'].edge_index = torch.randint(0, 100, (2, 200))

print("validate():", data.validate())  # Returns True although dtypes are invalid

device = torch_geometric.device('auto')
print(device) # e.g. mps on my machine
data = data.to(device) # silently fails to move the numpy arrays

# Check what actually happened
print("x device after .to():", data['user'].x.device)  # Still shows 'cpu'
print("x type:", type(data['user'].x))  # numpy.ndarray!

# try to use it in a model and it failse
data = ToUndirected()(data)

class Encoder(torch.nn.Module):
    def __init__(self, hidden_channels):
        super().__init__()
        self.conv = SAGEConv((-1, -1), hidden_channels)
    
    def forward(self, x, edge_index):
        return self.conv(x, edge_index).relu()

encoder = Encoder(32)
encoder = to_hetero(encoder, data.metadata(), aggr='sum')
encoder = encoder.to(device)

out = encoder(data.x_dict, data.edge_index_dict)

The encoder gets up to Aggregate stage and then fails with a cryptic AttributeError: 'NoneType' object has no attribute 'dim' 😕.

There are several places this could be caught / dealt with earlier:

1. On assignment: data['user'].x = numpy_array should either auto-convert to torch or raise a clear error
2. In .validate(): Should check that all x, edge_index, etc. are actually torch tensors - i.e. check dtypes as well as structure
3. In .to(device): if it encounters nested numpy arrays it should either auto-convert to tenor or raise a clear error instead of silently skipping them.

It is trivial to convert to a torch tensor, if there is a clear error message, but much harder to debug a message like what I got...

Thougth this was worth sharing to save some other people time 😃

Versions

PyTorch version: 2.9.0
Is debug build: False
CUDA used to build PyTorch: None
ROCM used to build PyTorch: N/A

OS: macOS 26.2 (arm64)
GCC version: Could not collect
Clang version: 17.0.0 (clang-1700.0.13.3)
CMake version: Could not collect
Libc version: N/A

Python version: 3.13.1 (main, Dec  3 2024, 17:59:52) [Clang 16.0.0 (clang-1600.0.26.4)] (64-bit runtime)
Python platform: macOS-26.2-arm64-arm-64bit-Mach-O
Is CUDA available: False
CUDA runtime version: No CUDA
CUDA_MODULE_LOADING set to: N/A
GPU models and configuration: No CUDA
Nvidia driver version: No CUDA
cuDNN version: No CUDA
Is XPU available: False
HIP runtime version: N/A
MIOpen runtime version: N/A
Is XNNPACK available: True
Caching allocator config: N/A

CPU:
Apple M3 Pro

Versions of relevant libraries:
[pip3] flake8==7.3.0
[pip3] mypy==1.18.2
[pip3] mypy_extensions==1.1.0
[pip3] numpy==2.3.4
[pip3] torch==2.9.0
[pip3] torch-geometric==2.7.0
[conda] Could not collect```

[Gabriel-Kissin]

The output I get from the MRE:

validate(): True
mps
x device after .to(): cpu
x type: <class 'numpy.ndarray'>

Full traceback:

---------------------------------------------------------------------------
AttributeError                            Traceback (most recent call last)
Cell In[1], line 39
     36 encoder = to_hetero(encoder, data.metadata(), aggr='sum')
     37 encoder = encoder.to(device)
---> 39 out = encoder(data.x_dict, data.edge_index_dict)

File ~/code/L/l_graph_analytics/.venv/lib/python3.13/site-packages/torch/fx/graph_module.py:837, in GraphModule.recompile.<locals>.call_wrapped(self, *args, **kwargs)
    836 def call_wrapped(self, *args, **kwargs):
--> 837     return self._wrapped_call(self, *args, **kwargs)

File ~/code/L/l_graph_analytics/.venv/lib/python3.13/site-packages/torch/fx/graph_module.py:413, in _WrappedCall.__call__(self, obj, *args, **kwargs)
    411     raise e.with_traceback(None)  # noqa: B904
    412 else:
--> 413     raise e

File ~/code/L/l_graph_analytics/.venv/lib/python3.13/site-packages/torch/fx/graph_module.py:400, in _WrappedCall.__call__(self, obj, *args, **kwargs)
    398         return self.cls_call(obj, *args, **kwargs)
    399     else:
--> 400         return super(self.cls, obj).__call__(*args, **kwargs)  # type: ignore[misc]
    401 except Exception as e:
    402     assert e.__traceback__

File ~/code/L/l_graph_analytics/.venv/lib/python3.13/site-packages/torch/nn/modules/module.py:1775, in Module._wrapped_call_impl(self, *args, **kwargs)
   1773     return self._compiled_call_impl(*args, **kwargs)  # type: ignore[misc]
   1774 else:
-> 1775     return self._call_impl(*args, **kwargs)

File ~/code/L/l_graph_analytics/.venv/lib/python3.13/site-packages/torch/nn/modules/module.py:1786, in Module._call_impl(self, *args, **kwargs)
   1781 # If we don't have any hooks, we want to skip the rest of the logic in
   1782 # this function, and just call forward.
   1783 if not (self._backward_hooks or self._backward_pre_hooks or self._forward_hooks or self._forward_pre_hooks
   1784         or _global_backward_pre_hooks or _global_backward_hooks
   1785         or _global_forward_hooks or _global_forward_pre_hooks):
-> 1786     return forward_call(*args, **kwargs)
   1788 result = None
   1789 called_always_called_hooks = set()

File <eval_with_key>.1:11, in forward(self, x, edge_index)
      9 edge_index__user__likes__item = edge_index_dict.get(('user', 'likes', 'item'), None)
     10 edge_index__item__rev_likes__user = edge_index_dict.get(('item', 'rev_likes', 'user'), None);  edge_index_dict = None
---> 11 conv__item = self.conv.user__likes__item((x__user, x__item), edge_index__user__likes__item);  edge_index__user__likes__item = None
     12 conv__user = self.conv.item__rev_likes__user((x__item, x__user), edge_index__item__rev_likes__user);  x__item = x__user = edge_index__item__rev_likes__user = None
     13 relu__user = conv__user.relu();  conv__user = None

File ~/code/L/l_graph_analytics/.venv/lib/python3.13/site-packages/torch/nn/modules/module.py:1775, in Module._wrapped_call_impl(self, *args, **kwargs)
   1773     return self._compiled_call_impl(*args, **kwargs)  # type: ignore[misc]
   1774 else:
-> 1775     return self._call_impl(*args, **kwargs)

File ~/code/L/l_graph_analytics/.venv/lib/python3.13/site-packages/torch/nn/modules/module.py:1786, in Module._call_impl(self, *args, **kwargs)
   1781 # If we don't have any hooks, we want to skip the rest of the logic in
   1782 # this function, and just call forward.
   1783 if not (self._backward_hooks or self._backward_pre_hooks or self._forward_hooks or self._forward_pre_hooks
   1784         or _global_backward_pre_hooks or _global_backward_hooks
   1785         or _global_forward_hooks or _global_forward_pre_hooks):
-> 1786     return forward_call(*args, **kwargs)
   1788 result = None
   1789 called_always_called_hooks = set()

File ~/code/L/l_graph_analytics/.venv/lib/python3.13/site-packages/torch_geometric/nn/conv/sage_conv.py:134, in SAGEConv.forward(self, x, edge_index, size)
    131     x = (self.lin(x[0]).relu(), x[1])
    133 # propagate_type: (x: OptPairTensor)
--> 134 out = self.propagate(edge_index, x=x, size=size)
    135 out = self.lin_l(out)
    137 x_r = x[1]

File /var/folders/1_/v1q0vq3x03q3vxq28ctc039c0000gp/T/torch_geometric.nn.conv.sage_conv_SAGEConv_propagate_3280mso0.py:229, in propagate(self, edge_index, x, size)
    221             kwargs = CollectArgs(
    222                 x_j=kwargs.x_j,
    223                 index=hook_kwargs['index'],
    224                 ptr=hook_kwargs['ptr'],
    225                 dim_size=hook_kwargs['dim_size'],
    226             )
    227 # End Aggregate Forward Pre Hook #######################################
--> 229 out = self.aggregate(
    230     out,
    231     index=kwargs.index,
    232     ptr=kwargs.ptr,
    233     dim_size=kwargs.dim_size,
    234 )
    236 # Begin Aggregate Forward Hook #########################################
    237 if not torch.jit.is_scripting() and not is_compiling():

File ~/code/L/l_graph_analytics/.venv/lib/python3.13/site-packages/torch_geometric/nn/conv/message_passing.py:594, in MessagePassing.aggregate(self, inputs, index, ptr, dim_size)
    577 def aggregate(
    578     self,
    579     inputs: Tensor,
   (...)    582     dim_size: Optional[int] = None,
    583 ) -> Tensor:
    584     r"""Aggregates messages from neighbors as
    585     :math:igoplus_{j \in \mathcal{N}(i)}`.
    586 
   (...)    592     as specified in :meth:`__init__` by the :obj:`aggr` argument.
    593     """
--> 594     return self.aggr_module(inputs, index, ptr=ptr, dim_size=dim_size,
    595                             dim=self.node_dim)

File ~/code/L/l_graph_analytics/.venv/lib/python3.13/site-packages/torch_geometric/experimental.py:117, in disable_dynamic_shapes.<locals>.decorator.<locals>.wrapper(*args, **kwargs)
    114 @functools.wraps(func)
    115 def wrapper(*args: Any, **kwargs: Any) -> Any:
    116     if not is_experimental_mode_enabled('disable_dynamic_shapes'):
--> 117         return func(*args, **kwargs)
    119     for required_arg in required_args:
    120         index = required_args_pos[required_arg]

File ~/code/L/l_graph_analytics/.venv/lib/python3.13/site-packages/torch_geometric/nn/aggr/base.py:112, in Aggregation.__call__(self, x, index, ptr, dim_size, dim, **kwargs)
    101 @disable_dynamic_shapes(required_args=['dim_size'])
    102 def __call__(
    103     self,
   (...)    109     **kwargs,
    110 ) -> Tensor:
--> 112     if dim >= x.dim() or dim < -x.dim():
    113         raise ValueError(f"Encountered invalid dimension '{dim}' of "
    114                          f"source tensor with {x.dim()} dimensions")
    116     if index is None and ptr is None:

AttributeError: 'NoneType' object has no attribute 'dim'

[Gabriel-Kissin]

Changing in the MRE to

- data['user'].x = np.random.randn(100, 64)  # numpy array, not tensor
+ data['user'].x = torch.tensor(np.random.randn(100, 64), dtype=torch.float)
- data['item'].x = np.random.randn(100, 64)   # numpy array, not tensor
+ data['item'].x = torch.tensor(np.random.randn(100, 64), dtype=torch.float)

fixes the issue as these are now tensors 😄