Introduction

When you use SparseCategoricalCrossentropy in Keras, the true class labels are integer class indices, not one-hot vectors. Those integers must line up directly with the positions of the model's output units, so for N classes the valid labels are normally 0 through N - 1.

What the Labels Actually Mean

Suppose your model ends with:

model = tf.keras.Sequential([
    tf.keras.layers.Dense(3, activation="softmax")
])

That output has three positions:

• index 0
• index 1
• index 2

With SparseCategoricalCrossentropy, the ground-truth label for each example must be one of those integer indices.

So the labels are not:

• '"cat", "dog", "bird"'
• one-hot vectors such as [0, 1, 0]

They are:

• '0'
• '1'
• '2'

Concrete Example

Imagine these semantic classes:

class_names = ["cat", "dog", "bird"]

A valid label encoding is:

0 -> cat
1 -> dog
2 -> bird

If the model predicts:

[0.1, 0.7, 0.2]

then the true sparse label should be 1 if the correct class is dog, because dog is at output index 1.

Minimal Keras Example

1import tensorflow as tf
2import numpy as np
3
4x = np.array([
5    [0.0, 0.1],
6    [1.0, 1.1],
7    [2.0, 2.1],
8    [0.2, 0.0],
9    [1.1, 1.0],
10    [2.2, 1.9],
11], dtype="float32")
12
13y = np.array([0, 1, 2, 0, 1, 2], dtype="int32")
14
15model = tf.keras.Sequential([
16    tf.keras.layers.Input(shape=(2,)),
17    tf.keras.layers.Dense(16, activation="relu"),
18    tf.keras.layers.Dense(3, activation="softmax"),
19])
20
21model.compile(
22    optimizer="adam",
23    loss=tf.keras.losses.SparseCategoricalCrossentropy(),
24    metrics=["accuracy"],
25)
26
27model.fit(x, y, epochs=5, verbose=0)

The label array y contains integer class IDs, not one-hot rows.

Difference from CategoricalCrossentropy

This is the essential distinction:

• 'CategoricalCrossentropy expects one-hot encoded targets'
• 'SparseCategoricalCrossentropy expects integer class indices'

So for three classes:

1# sparse target
21
3
4# categorical target
5[0, 1, 0]

Both represent the same semantic class, but they are fed to the model differently.

Class Names Are Your Responsibility

Keras does not know that 0 means cat unless you define that mapping yourself. The loss function only sees integer indices and prediction positions.

A common pattern is:

1class_names = ["cat", "dog", "bird"]
2
3predictions = model.predict(x[:1], verbose=0)
4predicted_index = int(tf.argmax(predictions[0]))
5predicted_name = class_names[predicted_index]
6
7print(predicted_index, predicted_name)

This external mapping is what turns raw model outputs into human-readable labels.

Output Layer and from_logits

If your final layer uses softmax, the model outputs probabilities and from_logits=False is the normal default.

If your final layer omits softmax and returns raw scores, configure the loss accordingly:

loss = tf.keras.losses.SparseCategoricalCrossentropy(from_logits=True)

This changes how the loss interprets the predictions, but it does not change what the labels are. The labels are still integer class indices.

Common Pitfalls

The biggest mistake is using one-hot encoded targets with SparseCategoricalCrossentropy. That is the wrong target format for this loss and will often produce shape or semantic mismatches.

Another issue is using labels that do not start at 0 or do not match the output width. If your output layer has 3 units, labels such as 1, 2, and 3 are wrong unless you first remap them to 0, 1, and 2.

Finally, do not confuse class IDs with class names. The loss function works with indices only. Human-readable names belong in a separate mapping layer in your code or data pipeline.

Summary

• 'SparseCategoricalCrossentropy expects integer class labels, not one-hot vectors.'
• Those labels must match the output indices of the model, typically 0 to num_classes - 1.
• Class names such as "cat" or "dog" must be mapped to integer IDs before training.
• 'from_logits changes prediction interpretation, not label format.'
• Use CategoricalCrossentropy instead if your targets are one-hot encoded.