The error message ValueError: num_samples should be a positive integer value, but got num_samples=0 is one of the most common hurdles encountered when setting up data pipelines in machine learning frameworks, particularly PyTorch. This error effectively halts the training process before the first epoch even begins, signaling that the system expected a list of data points to process but found an empty set instead.

Understanding why this happens requires a look into how data loaders interpret dataset sizes and how specific library configurations or environmental factors can inadvertently reduce a dataset to zero.

Defining the Context of num_samples 0

Depending on the framework being used, num_samples = 0 can carry vastly different meanings. Distinguishing between a configuration choice and a runtime error is the first step in troubleshooting.

As a Functional Default in MindSpore

In certain frameworks like MindSpore, setting the num_samples parameter to 0 is not an error. Instead, it serves as a programmatic shorthand. In this context, 0 typically instructs the data loading pipeline to use all available samples in the dataset. It acts as a "no limit" flag, ensuring that the entire directory or data file is processed without truncation.

As a Critical Error in PyTorch

In PyTorch, the DataLoader and its associated Sampler classes (like RandomSampler or SequentialSampler) require a strictly positive integer for num_samples. The framework uses this value to determine the range of indices it can shuffle or iterate through. If the internal __len__ method of a dataset returns 0, PyTorch throws a ValueError because it cannot perform sampling operations on a non-existent collection of data.

Common Root Causes of num_samples 0 Errors

When PyTorch reports that it "got num_samples=0," the problem rarely lies within the DataLoader itself. Instead, the issue is almost always upstream, located in the dataset initialization or the environment where the code is executing.

1. Incorrect Dataset Paths and File Extensions

The most frequent cause is a simple path mismatch. If a torchvision.datasets.ImageFolder or a custom dataset class points to a directory that is empty or does not exist, the resulting dataset object will have a length of zero.

A subtle variation of this problem involves file extensions. Many pre-built dataset loaders filter files based on specific suffixes like .jpg or .png. If a dataset contains only .webp files but the loader is configured to search for .jpg, the filtering logic will yield zero matches, triggering the error. This often occurs when moving code between local machines and remote GPU clusters where data sync processes might have failed or changed file structures.

2. Logic Failures in random_split

When dividing a large dataset into training, validation, and test sets using torch.utils.data.random_split, developers often use percentages (e.g., 80% train, 20% val). If the total number of samples is very small or if the calculation results in a rounding error that yields zero, the resulting subset will be empty.

For instance, applying a 10% split to a dataset that accidentally only contains 4 images (due to previous loading errors) might result in a subset with a calculated length of 0.4. Depending on how the splitting function handles integers, this can result in an empty split, leading to the num_samples=0 error when that specific subset is passed to a DataLoader.

3. Conflicting DataLoader Parameters

In complex training scripts, developers sometimes manually define a batch_sampler or a custom sampler. A common mistake is providing a shuffle=True argument to the DataLoader while also providing a custom sampler. PyTorch's DataLoader is designed to be mutually exclusive regarding these parameters; however, if the logic determining the sampler's size fails and returns zero, the error message will specifically target the num_samples value.

4. Library Version Incompatibility: The Pandas 3.0 Case

Recent updates in the Python ecosystem have introduced unexpected breaking changes. A notable example is the transition to Pandas 3.0. In certain anomaly detection libraries and custom data loaders that rely on Pandas to parse metadata or CSV files, the way indices or row counts are handled has changed. Users running older training scripts in environments where Pandas has been updated to 3.0 may find that their dataframes are not being read correctly, resulting in an empty dataset object being passed to PyTorch.

5. Overly Restrictive Filtering and Preprocessing

If a custom dataset class includes filtering logic in its __init__ method—such as removing images below a certain resolution or excluding specific labels—it is possible for the filter to be too aggressive. In scenarios where the filter excludes 100% of the available data, the len(dataset) will naturally be zero.

How to Troubleshoot the num_samples 0 Error

Solving this error requires a systematic check of the data pipeline, moving from the raw files up to the DataLoader object.

Step 1: Verify the Dataset Length Immediately

Before passing a dataset object to the DataLoader, insert a diagnostic print statement to check its length: