Introduction

Key ... not found in checkpoint means TensorFlow tried to restore a variable name that does not exist in the checkpoint file. The core issue is almost always mismatch: the checkpoint was written from one variable structure, but you are now restoring into a different model structure, naming scheme, or object graph.

What A TensorFlow Checkpoint Stores

A checkpoint does not store your source code. It stores values associated with variable names or tracked objects.

That means restore succeeds only when TensorFlow can match the saved entries to the variables in the current model.

Typical mismatch causes are:

• renamed layers or scopes
• changed model architecture
• restoring the wrong checkpoint
• trying to load Keras weights into a different object graph
• variables not created yet at restore time

First Inspect The Checkpoint Contents

Before guessing, list what is actually inside the checkpoint.

1import tensorflow as tf
2
3for name, shape in tf.train.list_variables("/path/to/checkpoint"):
4    print(name, shape)

This tells you the exact variable keys TensorFlow expects to find during restore.

If the missing key is not listed there, the checkpoint simply does not contain it.

Example Of A Mismatch

Suppose the checkpoint was created from a model with one dense layer named dense, and you later change the model to use a layer named classifier.

1import tensorflow as tf
2
3model = tf.keras.Sequential([
4    tf.keras.layers.Dense(8, activation="relu", name="classifier")
5])
6model(tf.zeros((1, 4)))

If the checkpoint was saved from a differently named layer structure, TensorFlow may not find matching keys during restore.

Make Sure Variables Exist Before Restoring

In TensorFlow 2.x and Keras, variables are often created lazily the first time the model sees input. If you restore too early, TensorFlow may not have the expected variable objects yet.

1import tensorflow as tf
2
3model = tf.keras.Sequential([
4    tf.keras.layers.Dense(8, activation="relu"),
5    tf.keras.layers.Dense(1)
6])
7
8model(tf.zeros((1, 4)))
9model.load_weights("/path/to/weights")

That first dummy call builds the variables so the weight loader has something concrete to match against.

Match The Saving And Loading Style

TensorFlow offers several save and restore paths:

• 'tf.train.Checkpoint'
• 'model.save_weights() and model.load_weights()'
• full Keras model saving

These mechanisms overlap, but they are not identical. If you save with one object structure and restore with a different one, mismatches are more likely.

A stable pattern is to use the same style on both sides.

checkpoint = tf.train.Checkpoint(model=model)
checkpoint.restore("/path/to/ckpt")

Partial Restore Is Sometimes Acceptable

If you intentionally changed the model and only want matching variables restored, TensorFlow gives you tools to tolerate partial matches.

checkpoint = tf.train.Checkpoint(model=model)
status = checkpoint.restore("/path/to/ckpt")
status.expect_partial()

This is useful when you know some variables will be missing, such as when fine-tuning a changed head on top of a reused backbone.

But use this deliberately. Do not silence mismatch warnings blindly.

A Good Debugging Sequence

When this error appears:

1. inspect checkpoint variable names
2. inspect current model variable names
3. verify the model is built before restore
4. confirm you are restoring the correct checkpoint file
5. decide whether exact match or partial restore is intended

That workflow is usually faster than trial-and-error renaming.

Common Pitfalls

A common mistake is changing layer names or scopes and expecting old checkpoints to load transparently. TensorFlow restore logic depends heavily on consistent naming or object tracking.

Another issue is loading weights before the model variables have been created. In Keras, a model that has never seen input may not yet have the variables you think it has.

Developers also sometimes mix checkpoint formats, such as saving with one API and restoring with assumptions that belong to another.

Finally, do not hide real incompatibilities with expect_partial() unless partial restore is genuinely the intended behavior.

Summary

• 'Key ... not found in checkpoint means the current restore target does not match what the checkpoint contains.'
• Inspect checkpoint keys with tf.train.list_variables before guessing.
• Build model variables before restoring when using lazy-created Keras models.
• Keep save and restore APIs consistent across training and loading code.
• Use partial restore only when the mismatch is intentional.