Troubleshooting¶

The errors below are raised on purpose, at the point where Tesseract-Torch can still say what went wrong. Each entry lists the message you will see, why it happens, and what to do about it.

`apply_tesseract` inside a `torch.func` transform¶

RuntimeError: apply_tesseract does not support torch.func transforms (torch.func.vjp, torch.func.jvp, torch.func.grad, etc.). Use the standard autograd API instead:
  - Reverse mode: result['y'].backward() or torch.autograd.grad()
  - Forward mode: torch.autograd.forward_ad (dual tensors)

torch.func.vmap reports the same limitation in PyTorch’s own words:

RuntimeError: You tried to vmap over _TesseractFunction, but it does not have vmap support. Please override and implement the vmap staticmethod or set generate_vmap_rule=True.

Cause. torch.func transforms (torch.func.vjp, torch.func.jvp, torch.func.grad) trace your function with functionalized tensors that have no backing storage. A Tesseract endpoint receives NumPy arrays, and such a tensor cannot be converted into one. torch.func.vmap is refused a step earlier, by PyTorch itself, because the underlying autograd.Function defines no batching rule.

Fix. Use PyTorch’s standard autograd API, which apply_tesseract supports in both modes:

# Reverse mode
x = torch.tensor([1.0, 2.0, 3.0], requires_grad=True)
result = apply_tesseract(tess, inputs={"x": x})
(grad_x,) = torch.autograd.grad(result["y"].sum(), x)

# Forward mode
import torch.autograd.forward_ad as fwAD

with fwAD.dual_level():
    x_dual = fwAD.make_dual(torch.tensor([1.0, 2.0, 3.0]), torch.ones(3))
    result = apply_tesseract(tess, inputs={"x": x_dual})
    _, jvp = fwAD.unpack_dual(result["y"])

Reverse-mode AD against a Tesseract without `vector_jacobian_product`¶

NotImplementedError: Vector Jacobian Product (VJP) not implemented for this Tesseract.

Cause. .backward() and torch.autograd.grad are dispatched to the Tesseract’s vector_jacobian_product endpoint. The Tesseract you called only defines apply, so there is nothing to dispatch to. The forward pass itself succeeds; the error appears when the backward pass runs.

Fix. Either implement vector_jacobian_product in the Tesseract, or do not ask for gradients through it: pass inputs without requires_grad=True and it behaves as a plain, non-differentiable operation.

Forward-mode AD against a Tesseract without `jacobian_vector_product`¶

NotImplementedError: Jacobian Vector Product (JVP) not implemented for this Tesseract.

Cause. The forward-mode counterpart of the previous entry: a call inside torch.autograd.forward_ad.dual_level() with dual tensors as inputs is dispatched to the Tesseract’s jacobian_vector_product endpoint, which this Tesseract does not define.

Fix. Implement jacobian_vector_product in the Tesseract, or pass plain (non-dual) tensors.

List-valued differentiable fields¶

NotImplementedError: List-valued differentiable inputs are not supported yet: xs.[]. Use a dict-valued field, or keep the list entries as separate schema fields.

Cause. Tesseract-Torch walks nested dictionaries and sub-models to find differentiable leaves, but a list[Differentiable[...]] field arrives as a single opaque value, so its tensors cannot be registered with autograd. The same applies to list-valued differentiable outputs.

Fix. Change the schema to a dict-valued field, or to one field per entry:

class InputSchema(BaseModel):
    xs: dict[str, Differentiable[Array[(3,), Float32]]]

and call it with {"xs": {"first": x0, "second": x1}}.

Forward-mode AD with an in-process PyTorch Tesseract¶

RuntimeError: Error running Tesseract API jacobian_vector_product: Nested forward mode AD is not supported at the moment

Cause. Tesseract.from_tesseract_api(...) runs the Tesseract in your own Python process. If its jacobian_vector_product is itself implemented with torch.func.jvp (as the Tesseracts in examples/ are), that call opens a second forward-AD level inside your dual_level() block, which PyTorch refuses.

Fix. Serve the Tesseract in a container (Tesseract.from_image(...) followed by .serve(), or a with block), which is how the examples run it. Reverse-mode AD is unaffected either way.