Introduction

The TensorFlow error Shape must be rank 1 but is rank 0 for 'ParseExample/ParseExample' usually means the parsing API and the input tensor rank do not match. In practice, this often happens when tf.io.parse_example is given one serialized example instead of a batch of serialized examples. The fix is usually straightforward once you separate parse_example from parse_single_example and verify the shapes flowing through the dataset pipeline.

Understand the Difference Between the Two Parsing APIs

TensorFlow provides two similar functions:

• 'tf.io.parse_single_example for one serialized example'
• 'tf.io.parse_example for a batch of serialized examples'

That distinction is the root of this error.

If you pass a scalar string tensor, such as one serialized record, into parse_example, TensorFlow complains because that op expects a rank-1 batch input.

Wrong pattern:

1import tensorflow as tf
2
3feature_spec = {
4    "label": tf.io.FixedLenFeature([], tf.int64),
5}
6
7serialized = tf.constant(b"...")  # one serialized example
8parsed = tf.io.parse_example(serialized, feature_spec)

Here, serialized is rank 0, not rank 1.

Use parse_single_example for One Record

If your dataset mapping function processes one example at a time, use parse_single_example:

1import tensorflow as tf
2
3feature_spec = {
4    "label": tf.io.FixedLenFeature([], tf.int64),
5}
6
7
8def parse_record(serialized):
9    parsed = tf.io.parse_single_example(serialized, feature_spec)
10    return parsed["label"]

This is the standard pattern for:

dataset = tf.data.TFRecordDataset(["train.tfrecord"]).map(parse_record)

Each dataset element is one serialized record, so parse_single_example matches the shape correctly.

Use parse_example Only After Batching

parse_example is appropriate when the input tensor already contains a batch of serialized examples.

1import tensorflow as tf
2
3feature_spec = {
4    "label": tf.io.FixedLenFeature([], tf.int64),
5}
6
7
8def parse_batch(serialized_batch):
9    parsed = tf.io.parse_example(serialized_batch, feature_spec)
10    return parsed["label"]
11
12
13dataset = (
14    tf.data.TFRecordDataset(["train.tfrecord"])
15    .batch(32)
16    .map(parse_batch)
17)

Now the input to parse_example is rank 1, which matches what the op expects.

That is the central correction for this error: either parse one example at a time, or batch first and use the batch parser.

Check the Feature Spec Separately from the Input Rank

Sometimes people assume the error is about feature shapes such as FixedLenFeature([1], ...) versus FixedLenFeature([], ...). That can cause parse errors too, but it is a different issue.

Example feature spec:

1feature_spec = {
2    "image_raw": tf.io.FixedLenFeature([], tf.string),
3    "label": tf.io.FixedLenFeature([], tf.int64),
4}

If the error text specifically says ParseExample expected rank 1 but got rank 0, start by checking the rank of the serialized input tensor, not just the feature description.

A quick debug step:

def debug_parse(serialized):
    tf.print("serialized shape:", tf.shape(serialized), "rank:", tf.rank(serialized))
    return tf.io.parse_single_example(serialized, feature_spec)

That usually reveals whether the pipeline is feeding one record or a batch.

Keep the Dataset Pipeline Shape-Aware

A common safe pattern is:

dataset = tf.data.TFRecordDataset(["train.tfrecord"])
dataset = dataset.map(lambda x: tf.io.parse_single_example(x, feature_spec))

or, if batching is desired before parsing:

dataset = tf.data.TFRecordDataset(["train.tfrecord"])
dataset = dataset.batch(32)
dataset = dataset.map(lambda x: tf.io.parse_example(x, feature_spec))

Both are correct. Mixing the two styles is what creates the rank mismatch.

Common Pitfalls

• Calling tf.io.parse_example inside a dataset map that receives one serialized record at a time.
• Assuming the error is always about FixedLenFeature shape rather than serialized input rank.
• Batching after parsing and then expecting parse_example semantics earlier in the pipeline.
• Debugging only the feature spec without printing input rank and dataset element shape.
• Treating parse_example and parse_single_example as interchangeable APIs.

Summary

• 'parse_single_example is for one serialized example, while parse_example is for a batch.'
• This error usually means a scalar serialized tensor was passed to the batch parser.
• Fix it by switching to parse_single_example or batching before parse_example.
• Check input rank separately from the feature-description structure.
• In TensorFlow input pipelines, shape awareness is usually the fastest path to the real fix.