Practice Now
tf.nn.in_top_k
targets out of range
TensorFlow error
machine learning troubleshooting
deep learning debugging

tf.nn.in_top_k targets out of range

ML System Design practice on Codemia

Design recommenders, ranking systems and training pipelines the way ML interviews actually ask for them, with worked solutions.

Practice ML system design
Deep LearningTensorFlow & KerasMachine LearningDebugging & Errors

Introduction

The tf.nn.in_top_k targets out of range error occurs when a target label value is greater than or equal to the number of classes (columns) in the predictions tensor. For example, if your model outputs 10 classes (indices 0-9) but a label has value 10, TensorFlow raises this error. The fix is to ensure all target labels are in the range [0, num_classes - 1] and that the predictions tensor has the correct number of output columns matching your label space.

The Error

python
1import tensorflow as tf
2
3predictions = tf.constant([[0.1, 0.9, 0.0],   # 3 classes (indices 0, 1, 2)
4                           [0.8, 0.1, 0.1]])
5targets = tf.constant([1, 3])  # ERROR: target 3 is out of range for 3 classes
6
7result = tf.nn.in_top_k(predictions, targets, k=1)
8# InvalidArgumentError: targets[1] is out of range

tf.nn.in_top_k checks whether the true class index (targets[i]) is among the top k predictions. If targets[i] >= num_classes, there is no corresponding column in the predictions tensor.

How tf.nn.in_top_k Works

python
1import tensorflow as tf
2
3predictions = tf.constant([[0.1, 0.9, 0.0],
4                           [0.8, 0.1, 0.1],
5                           [0.3, 0.3, 0.4]])
6targets = tf.constant([1, 0, 2])
7
8# Is the true class in the top 1 prediction?
9top1 = tf.nn.in_top_k(predictions, targets, k=1)
10# [True, True, True]
11
12# Is the true class in the top 2 predictions?
13top2 = tf.nn.in_top_k(predictions, targets, k=2)
14# [True, True, True]

Parameters:

  • predictions: float tensor of shape (batch_size, num_classes)
  • targets: int tensor of shape (batch_size,) with values in [0, num_classes - 1]
  • k: how many top predictions to check

Common Causes and Fixes

Cause 1: Labels Start at 1 Instead of 0

python
1# Labels are 1-indexed (common in some datasets)
2targets = tf.constant([1, 2, 3])  # 3 classes but values 1-3
3num_classes = 3  # Model outputs columns 0, 1, 2
4
5# Fix: subtract 1 to convert to 0-indexed
6targets_fixed = targets - 1  # [0, 1, 2]
7result = tf.nn.in_top_k(predictions, targets_fixed, k=1)

Cause 2: Model Output Dimension Mismatch

python
1# Model outputs 5 classes but labels go up to 9
2model = tf.keras.Sequential([
3    tf.keras.layers.Dense(5, activation='softmax')  # Only 5 outputs
4])
5
6# Fix: match output dimension to number of classes
7num_classes = 10
8model = tf.keras.Sequential([
9    tf.keras.layers.Dense(num_classes, activation='softmax')  # 10 outputs
10])

Cause 3: String Labels Not Properly Encoded

python
1import numpy as np
2
3# Raw labels
4labels = ["cat", "dog", "bird", "cat", "fish"]
5
6# Encode to integers
7unique_labels = sorted(set(labels))
8label_to_idx = {label: idx for idx, label in enumerate(unique_labels)}
9targets = np.array([label_to_idx[l] for l in labels])
10
11# Verify range
12print(f"Classes: {len(unique_labels)}, Max target: {targets.max()}")
13# Classes: 4, Max target: 3  — valid range [0, 3]

Cause 4: Data Corruption or Incorrect Preprocessing

python
1import numpy as np
2
3# Validate targets before using in_top_k
4targets = np.array([0, 1, 2, 255, 1])  # 255 is clearly wrong
5num_classes = 3
6
7# Check for out-of-range values
8invalid = targets >= num_classes
9if invalid.any():
10    print(f"Invalid targets at indices: {np.where(invalid)[0]}")
11    print(f"Invalid values: {targets[invalid]}")
12
13# Filter or clip
14targets_clipped = np.clip(targets, 0, num_classes - 1)

Using in_top_k for Evaluation Metrics

python
1import tensorflow as tf
2
3def top_k_accuracy(predictions, targets, k=5):
4    """Calculate top-k accuracy."""
5    # Validate targets
6    num_classes = predictions.shape[-1]
7    tf.debugging.assert_less(
8        targets, num_classes,
9        message=f"All targets must be < {num_classes}"
10    )
11
12    in_top_k = tf.nn.in_top_k(predictions, targets, k=k)
13    return tf.reduce_mean(tf.cast(in_top_k, tf.float32))
14
15# Example
16predictions = tf.random.uniform((100, 10))  # 100 samples, 10 classes
17targets = tf.random.uniform((100,), maxval=10, dtype=tf.int32)
18
19acc_top1 = top_k_accuracy(predictions, targets, k=1)
20acc_top5 = top_k_accuracy(predictions, targets, k=5)
21print(f"Top-1: {acc_top1:.2%}, Top-5: {acc_top5:.2%}")

TensorFlow 2.x API Note

In TensorFlow 2.x, the argument order changed:

python
1# TF 1.x
2tf.nn.in_top_k(predictions, targets, k)
3
4# TF 2.x — use keyword arguments for clarity
5tf.nn.in_top_k(targets=targets, predictions=predictions, k=k)
6
7# Or use the Keras metric
8metric = tf.keras.metrics.SparseTopKCategoricalAccuracy(k=5)
9metric.update_state(targets, predictions)
10print(metric.result())

Common Pitfalls

  • Labels starting at 1 instead of 0: Many datasets (especially from CSV files or MATLAB) use 1-based indexing. TensorFlow expects 0-based class indices. Subtract 1 from all labels before passing to in_top_k.
  • Mismatch between model output units and number of classes: If the final Dense layer has fewer units than the maximum label value, targets will be out of range. The output dimension must equal the total number of classes.
  • Using argmax output as targets instead of the original labels: tf.argmax(predictions) produces predicted class indices, not true labels. Pass the ground truth labels as targets, not the model's own predictions.
  • Not validating data after preprocessing: Data augmentation, shuffling, or batching can introduce corrupted labels. Add a tf.debugging.assert_less(targets, num_classes) check during development.
  • Confusing in_top_k with top_k: tf.nn.in_top_k returns a boolean tensor indicating whether targets are in the top k. tf.math.top_k returns the actual top k values and indices from a tensor. They serve different purposes.

Summary

  • The "targets out of range" error means a label value is >= the number of prediction columns
  • Ensure labels are 0-indexed and the model's output layer matches the number of classes
  • Use tf.debugging.assert_less() to catch out-of-range labels early
  • In TF 2.x, use keyword arguments or SparseTopKCategoricalAccuracy for top-k evaluation
  • Validate your data pipeline to confirm labels stay in the valid range after preprocessing
Related reading
Free course
Beginner
7 lessons
2 hours
Tackling System Design Interview Problems

A short course that equips you with the skills to approach system design interviews methodically.

Start the free course
Track what you have practised

A free account saves your progress, solutions and study plan across every problem on Codemia.

ML System Design practice on Codemia

Design recommenders, ranking systems and training pipelines the way ML interviews actually ask for them, with worked solutions.

Practice ML system design
Codemia
© 2026 Codemia
Resources
Legal
Social
All Rights Reserved.