Introduction

The error "Can't parse serialized example" usually means TensorFlow is trying to decode a TFRecord with a schema that does not match the data that was written. The file is often fine at the byte level; the real problem is a mismatch between how the example was serialized and how tf.io.parse_single_example expects to read it.

What TensorFlow Expects in a TFRecord

A TFRecord file normally stores serialized tf.train.Example messages. Each example contains named features, and each feature is stored as one of three protobuf list types: bytes_list, float_list, or int64_list.

When parsing, you must tell TensorFlow the exact shape and type you expect for each feature. If the parser expects a fixed-length integer but the record contains bytes, or if a required feature is missing, parsing fails.

Here is a minimal writer:

1import tensorflow as tf
2
3
4def make_example(name: bytes, age: int) -> bytes:
5    example = tf.train.Example(
6        features=tf.train.Features(
7            feature={
8                "name": tf.train.Feature(bytes_list=tf.train.BytesList(value=[name])),
9                "age": tf.train.Feature(int64_list=tf.train.Int64List(value=[age])),
10            }
11        )
12    )
13    return example.SerializeToString()
14
15
16with tf.io.TFRecordWriter("people.tfrecord") as writer:
17    writer.write(make_example(b"Alice", 30))
18    writer.write(make_example(b"Bob", 41))

If you write data like that, the parser must describe name as bytes and age as integer.

Matching the Parse Schema Correctly

This is the corresponding parser:

1import tensorflow as tf
2
3
4feature_spec = {
5    "name": tf.io.FixedLenFeature([], tf.string),
6    "age": tf.io.FixedLenFeature([], tf.int64),
7}
8
9
10def parse_record(serialized_example):
11    return tf.io.parse_single_example(serialized_example, feature_spec)
12
13
14dataset = tf.data.TFRecordDataset("people.tfrecord")
15dataset = dataset.map(parse_record)
16
17for item in dataset:
18    print(item["name"].numpy(), item["age"].numpy())

If age had been written as bytes or if the key were spelled years in the file, this parser would fail.

Common Reasons Parsing Fails

The most common cause is a type mismatch. For example, writing an integer feature and then parsing it as tf.string is enough to trigger the error.

Another frequent issue is using FixedLenFeature for data that is optional or variable-length. If a feature may be missing or may contain multiple values, use VarLenFeature or RaggedFeature instead of forcing a fixed scalar shape.

feature_spec = {
    "tokens": tf.io.VarLenFeature(tf.int64),
}

Compression mismatches can also break parsing. If the TFRecord file was written with GZIP compression, the dataset reader must declare the same compression type.

1dataset = tf.data.TFRecordDataset(
2    "compressed.tfrecord",
3    compression_type="GZIP",
4)

If you omit that setting, TensorFlow reads the bytes as ordinary TFRecord data and parsing quickly falls apart.

A Practical Debugging Approach

When the schema is unclear, read one record at a time and inspect it directly.

1import tensorflow as tf
2
3raw_dataset = tf.data.TFRecordDataset("people.tfrecord")
4
5for raw_record in raw_dataset.take(1):
6    example = tf.train.Example()
7    example.ParseFromString(raw_record.numpy())
8    print(example)

Printing the raw Example is often the fastest way to confirm the true feature names and stored types. It removes guesswork from the parser definition.

You should also keep the write and parse schemas close together in the codebase. Many TFRecord bugs happen because one script writes the data and another script later evolves its expectations without updating the serialization format.

Common Pitfalls

One common pitfall is assuming a scalar and a single-element list are interchangeable. TensorFlow parsing APIs care about how the feature was declared, so shape mismatches matter.

Another issue is missing required features. FixedLenFeature treats a missing feature as an error unless you provide a default value.

Developers also sometimes forget that strings in TFRecords are raw bytes. If you wrote encoded text, parse it as tf.string first and decode later if needed.

Finally, do not assume the file is corrupt just because parsing fails. In most cases the records are valid, but the parsing spec is wrong.

Summary

• TFRecord parsing errors usually come from schema mismatches, not from broken files.
• Make sure feature names, data types, and shapes match the way the examples were written.
• Use VarLenFeature for variable-length data instead of forcing FixedLenFeature.
• Match the compression type used when reading compressed TFRecords.
• Inspect a raw tf.train.Example directly when you need to confirm the real stored structure.