Choose the right PennyLane diff_method and fix gradient configuration errors

TL;DR

For "QuantumFunctionError: Backpropagation is only supported when shots=None.": use "adjoint" when the parameter count is large (much lower memory, similar runtime). Apply the method from step 2's matrix, not the one that worked in a tutorial with a different configuration.

QuantumFunctionError: Backpropagation is only supported when shots=None.

When to use

You are seeing this: The error message names the illegal combination directly, match it before changing anything. Use this skill when you run into "Choose the right PennyLane diff_method and fix gradient configuration errors".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Choose the right diff_method and fix gradient configuration errors in PennyLane

Use this when a PennyLane gradient call raises QuantumFunctionError, ValueError, or NotImplementedError naming the differentiation method, or when you are choosing diff_method for a new QNode. The error message names the illegal combination directly, match it before changing anything.

1. Read the exact error, it names the illegal combination

2. Pick diff_method from device x shots x measurement

Classify your configuration first; the matrix below gives the method:

• Simulator (default.qubit, lightning.qubit) + shots=None + qml.expval/qml.var/qml.probs: diff_method="best" (the default) resolves to backprop on default.qubit, exact and usually cheapest. Use "adjoint" when the parameter count is large (much lower memory, similar runtime). Both are simulator-only.
• Simulator + finite shots (shots=1000, etc.): only hardware-compatible methods work, "parameter-shift", "finite-diff", "hadamard". Backprop raises the shots=None error; adjoint warns and computes the gradient analytically anyway, so the gradient no longer matches the noisy forward pass.
• Hardware device: only "parameter-shift", "finite-diff", or "hadamard". Backprop and adjoint are never available, this is documented, not a bug.
• Circuit returns qml.state(): only "backprop" on a simulator with shots=None. Parameter-shift and adjoint both refuse (see the error table). Never on hardware.
• Circuit returns qml.sample or qml.counts: no gradient under any method or device. The QNode must return qml.expval (or qml.probs) to train.

3. Know the cost before you pick

Parameter-shift needs 2 circuit evaluations per trainable parameter per gradient step, so gradient cost scales linearly with parameter count. On simulators, backprop and adjoint are usually cheaper and exact, prefer them whenever the configuration in step 2 allows. Finite shots make parameter-shift gradients noisy estimators; that is expected, not a bug.

4. Checklist for the failing gradient call

1. Copy the full error text; match it to the table in step 1.

2. Confirm the three facts: device class (simulator vs hardware), shots setting (None vs finite), and the returned measurement type.

3. Apply the method from step 2's matrix, not the one that worked in a tutorial with a different configuration.

4. Re-run the gradient call (qml.grad(circuit)(params) or the interface's backward pass) and confirm the error is gone before tuning anything else.

Built from the PennyLane docs (interfaces guide: backprop/adjoint are simulator-only, parameter-shift/finite-diff/hadamard are hardware-compatible), the doc/introduction/unsupported_gradients.rst page (exact QuantumFunctionError texts for backprop-with-shots, adjoint-with-state, and device-jacobian), and recurring discuss.pennylane.ai threads (parameter-shift rule is hardware-compatible so it cannot differentiate qml.state(); broadcasted-tape parameter-shift limitation).