Can't register manually a tensor on a remote channel.

Error message

Can't register manually a tensor on a remote channel.

What it means

burn-remote's RegisterOperationChannel::register_tensor unconditionally panics: remote channels cannot manually register a tensor. Tensor registration is only meaningful for moving a tensor between local clients/devices; in the remote setting the tensor already lives server-side, so the operation is rejected. Use change_client_backend to move a RouterTensor to a different client instead.

Source

Thrown at crates/burn-remote/src/client/channel.rs:42

    }

    fn get_tensor_handle(tensor: &TensorIr, client: &Self::Client) -> RemoteTensorHandle {
        RemoteTensorHandle {
            client: client.clone(),
            tensor: tensor.clone(),
        }
    }

    fn register_tensor(
        _client: &Self::Client,
        _handle: RemoteTensorHandle,
        _shape: Shape,
        _dtype: burn_backend::DType,
    ) -> RouterTensor<Self::Client> {
        // This function is normally only used to move a tensor from a device to another.
        //
        // In other words, to change the client.
        panic!("Can't register manually a tensor on a remote channel.");
    }

    fn change_client_backend(
        tensor: RouterTensor<Self::Client>,
        target_device: &Self::Device, // target device
    ) -> RouterTensor<Self::Client> {
        // Get tensor handle from current client
        let original_client = tensor.client.clone();
        let desc = tensor.into_ir();
        let handle = Self::get_tensor_handle(&desc, &original_client);

        let handle = handle.change_backend(target_device);

        let id = handle.tensor.id;

        let target_client = get_client::<Self>(target_device);
        let router_tensor: RouterTensor<RemoteClient> =
            RouterTensor::new(id, handle.tensor.shape, handle.tensor.dtype, target_client);

View on GitHub (pinned to d16f7ba2ed)

Solutions

Use change_client_backend (the TensorHandle-based path) to move a RouterTensor to the target device/client instead of register_tensor.
Perform the tensor transfer server-side (on the remote worker) and only send back the resulting handle.
If you need local registration semantics, execute that portion of code on a local backend, not a remote channel.

Example fix

// before
let tensor = router_client.register(tensor, shape, dtype); // panics on remote channel
// after
let tensor = RouterTensor::change_client_backend(tensor, &target_device); // re-homes across clients

Defensive patterns

Strategy: try-catch

Validate before calling

// cannot be caught at type level; avoid calling register_tensor on remote channels.
// detect remote backend via marker if you have one:
fn is_remote_channel<C: burn_router::RegisterOperationChannel>(_: &C) -> bool {
    std::any::TypeId::of::<C>() == std::any::TypeId::of::<burn_remote::client::RemoteChannel>()
}

Try / catch

// burn-remote panics rather than returning Result; route around it:
let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
    channel.register(tensor, &shape, dtype)
}));
match result {
    Ok(t) => t,
    Err(_) => RouterTensor::change_client_backend(tensor, &target_device), // supported path
}

Prevention

Never call register_tensor on remote channels; use change_client_backend to re-home tensors.
Centralize cross-client tensor transfers in one helper so the remote-unsafe call can't leak in.
Keep device-to-device moves server-side when using burn-remote; only ship handles to the client.
Add a code-review/CI check forbidding register_tensor in code paths behind the remote backend.

When it happens

Trigger: Calling register_tensor directly on a burn-remote client channel, e.g. attempting to re-home a RouterTensor across remote clients or calling low-level register APIs on tensors fetched from a remote compute server.

Common situations: Trying to migrate a tensor between remote devices; porting local multi-device code to the remote backend; custom code that assumes the local register_tensor contract holds for remote channels.

Related errors

AI-assisted analysis of tracel-ai/burn@d16f7ba2ed (2026-09-05). Data as JSON: /api/errors/85fa71b526fe1ed4. Report an issue: GitHub.