Introduction

The TensorFlow and Keras training APIs need a clear plan for how input data will be consumed. When you pass raw tensors or NumPy arrays and the framework cannot infer that plan, you can hit an error saying that batch_size or steps is required for tensor or NumPy input data.

Why the Error Happens

Model APIs such as fit, evaluate, and predict do not process an entire dataset as one giant block unless you explicitly make that choice. They work in batches, which means Keras needs to know one of two things:

• how many samples belong in each batch
• how many batches should be consumed

With a plain NumPy array or eager tensor, the usual fix is batch_size. With iterators, repeated datasets, or streaming pipelines, the usual fix is a step count such as steps_per_epoch or steps.

The goal is not to satisfy a random argument check. The framework genuinely needs to know how to break the work into manageable units.

Use batch_size for Arrays and Finite Tensors

For ordinary in-memory training data, specify batch_size directly.

1import numpy as np
2import tensorflow as tf
3
4x_train = np.random.rand(1000, 20).astype("float32")
5y_train = np.random.randint(0, 2, size=(1000, 1)).astype("float32")
6
7model = tf.keras.Sequential([
8    tf.keras.layers.Input(shape=(20,)),
9    tf.keras.layers.Dense(16, activation="relu"),
10    tf.keras.layers.Dense(1, activation="sigmoid"),
11])
12
13model.compile(optimizer="adam", loss="binary_crossentropy", metrics=["accuracy"])
14
15history = model.fit(x_train, y_train, batch_size=32, epochs=3)

This is the most common fix because arrays and eager tensors usually represent a finite dataset that you already have in memory.

The same idea applies to prediction:

x_test = np.random.rand(100, 20).astype("float32")
predictions = model.predict(x_test, batch_size=16)
print(predictions.shape)

If you omit batching in a code path that requires it, Keras cannot decide how to iterate.

Use steps for Repeated or Streaming Input

If you use tf.data.Dataset and repeat it forever, Keras no longer knows when an epoch should stop. In that case, a step count is the right answer.

1import numpy as np
2import tensorflow as tf
3
4x_train = np.random.rand(1000, 20).astype("float32")
5y_train = np.random.randint(0, 2, size=(1000, 1)).astype("float32")
6
7dataset = tf.data.Dataset.from_tensor_slices((x_train, y_train))
8dataset = dataset.shuffle(1000).batch(32).repeat()
9
10model = tf.keras.Sequential([
11    tf.keras.layers.Input(shape=(20,)),
12    tf.keras.layers.Dense(16, activation="relu"),
13    tf.keras.layers.Dense(1, activation="sigmoid"),
14])
15
16model.compile(optimizer="adam", loss="binary_crossentropy")
17
18model.fit(dataset, epochs=3, steps_per_epoch=30)

Here the dataset is intentionally infinite because of .repeat(). Without steps_per_epoch, the training loop would not know when to end an epoch.

Prefer tf.data When Input Logic Gets Complex

If your input pipeline already needs shuffling, mapping, batching, prefetching, or file loading, move to tf.data instead of passing raw arrays through increasingly complex argument combinations.

1import tensorflow as tf
2
3features = tf.random.normal((256, 10))
4labels = tf.random.uniform((256, 1), maxval=2, dtype=tf.int32)
5
6train_ds = tf.data.Dataset.from_tensor_slices((features, labels))
7train_ds = train_ds.batch(32).prefetch(tf.data.AUTOTUNE)
8
9model = tf.keras.Sequential([
10    tf.keras.layers.Input(shape=(10,)),
11    tf.keras.layers.Dense(8, activation="relu"),
12    tf.keras.layers.Dense(1, activation="sigmoid"),
13])
14
15model.compile(optimizer="adam", loss="binary_crossentropy")
16model.fit(train_ds, epochs=2)

Once the dataset is already batched and finite, you often do not need a separate batch_size argument.

batch_size and steps Solve Different Problems

A common misunderstanding is treating batch_size and steps as interchangeable. They are related, but they mean different things.

• 'batch_size controls how many samples are processed per batch.'
• 'steps controls how many batches are consumed.'

If you have 1000 samples and batch_size=32, then one epoch is roughly 32 steps. If you also set steps_per_epoch=10, you are telling Keras to stop early after only 10 batches.

That can be useful, but it should be deliberate.

Debugging Checklist

When this error appears, check these questions in order:

• Is the input a raw NumPy array or tensor rather than a dataset object?
• Did I forget to pass batch_size for fit, evaluate, or predict?
• Did I call .repeat() on a dataset without providing steps_per_epoch?
• Am I mixing a generator-style pipeline with array-style arguments?

In practice, one of those cases usually explains the failure.

Common Pitfalls

The biggest pitfall is assuming that Keras will always guess a batching strategy from the shape alone. That is not true for every API path.

Another issue is using steps_per_epoch with finite arrays when a simple batch_size would be clearer and easier to reason about.

People also forget that repeated datasets are intentionally endless. If you repeat a dataset, you usually owe Keras a step count.

Finally, avoid combining too many input styles at once. Arrays, generators, and tf.data pipelines all work, but they should not be mixed casually.

Summary

• Keras needs either a batch size or a batch count when it cannot infer how to iterate input data.
• Use batch_size for ordinary in-memory tensors or NumPy arrays.
• Use steps or steps_per_epoch for repeated, streaming, or generator-like input.
• 'tf.data is usually the cleanest approach for nontrivial input pipelines.'
• Treat batch_size and steps as separate controls, not as interchangeable flags.