Why does tf.GradientTape.gradient() return None in TensorFlow, and how do you fix it?

## What None actually means `tape.gradient(target, sources)` returns a structure matching `sources`. A `None` entry is not "the gradient is zero"; it is "I have no recorded path from the target to this source, so I cannot even say it is zero". The distinction matters, because a genuine zero gradient is a modelling problem while a `None` is almost always a wiring bug in your code. Downstream, `None` is contagious: passing a list containing `None` to `optimizer.apply_gradients` at best warns and skips that variable, at worst fails outright — either way that weight never trains, which is a silent accuracy bug if only part of the model is affected. ## Cause 1: the source is not watched The tape watches trainable `tf.Variable` objects that are accessed inside its context. It does *not* watch constants, `tf.Tensor` inputs, NumPy arrays or Python floats, because tracking every tensor would be wasteful. If you need a gradient with respect to an input — for adversarial examples, saliency maps, input optimization — you must call `tape.watch(x)` inside the block before using `x`. Two related traps: a variable created with `trainable=False` is not auto-watched, and constructing the tape with `watch_accessed_variables=False` disables auto-watching entirely, so every source must be watched by hand. That flag is useful for restricting a backward pass to a subset of the model, and confusing when someone else set it. ## Cause 2: the op ran outside the context Only ops executed while the context is open are recorded. The most frequent version of this bug is closing the block after the forward pass and computing the loss on the next line. Another is computing part of the model — an embedding lookup, a preprocessing step — before entering the block, then differentiating with respect to something on that side of the boundary. ## Cause 3: the chain leaves TensorFlow Autograd only knows about TensorFlow ops. The moment you call `.numpy()` on an intermediate tensor, or hand a tensor to a NumPy or plain-Python function that returns a new array, the graph of recorded ops is severed. Execution continues happily and the numbers may even look right on the forward pass, which is why this one is hard to spot. The fix is to stay inside TensorFlow ops for anything on the differentiable path; use `.numpy()` only for logging, and only outside the tape. ## Cause 4: a non-differentiable link Some ops legitimately have no gradient. `tf.stop_gradient` exists specifically to cut the path — sometimes deliberately, sometimes left in from an experiment. Index-producing ops such as `tf.argmax` and `tf.math.argmin` return integers and are not differentiable. Casting to `tf.int32` or `tf.int64` anywhere on the path kills it, as does any op whose output dtype is integer or boolean. Control flow that picks a branch by a hard comparison can also produce a path with no gradient with respect to some inputs. When your loss involves a discrete decision, the answer is usually a differentiable relaxation (a softmax or a soft mask) rather than trying to force a gradient through the integer op. ## A debugging routine 1. Print which entries are `None` alongside `variable.name`. A pattern — for example every variable in one submodule — usually identifies the severed layer immediately. 2. Shorten the chain: inside the tape, keep intermediate tensors, then differentiate each intermediate against the source. The first intermediate that yields `None` sits just downstream of the break. Use `persistent=True` so you can take several gradients from one forward pass. 3. Check dtypes along that stretch. An unexpected integer or boolean tensor is the signature of cause 4. 4. Confirm the block boundaries. Re-read where the `with` closes relative to where the loss is computed. ## The one legitimate None If you are training a multi-head model and deliberately compute a loss that touches only one head, the other head's variables genuinely have no path to that loss, and `None` is correct. Handle it by passing only the relevant variable subset to `tape.gradient`, or by filtering the pairs before calling `apply_gradients` — not by silently converting the `None` to zeros, which hides the case where the disconnection was accidental.