What causes "ExternRef is not yet supported with wasm_c_api" in wasmerio/wasmer?

Use the sys or js backend where externrefs are supported

ExternRef is not yet supported with wasm_c_api

Error message

ExternRef is not yet supported with wasm_c_api

What it means

On the v8 backend (built atop wasm_c_api), `ExternRef::new` is not implemented: host-defined externref values cannot be wrapped. Calling it panics with this message; `downcast` is likewise a no-op stub.

Source

Thrown at lib/api/src/backend/v8/entities/external.rs:18

//! Data types, functions and traits for `v8` runtime's `ExternRef` implementation.
use crate::{
    store::{AsStoreMut, AsStoreRef},
    v8::vm::VMExternRef,
};
use std::any::Any;

#[derive(Debug, Clone)]
#[repr(transparent)]
/// A WebAssembly `extern ref` in the `v8` runtime.
pub struct ExternRef;

impl ExternRef {
    pub fn new<T>(_store: &mut impl AsStoreMut, _value: T) -> Self
    where
        T: Any + Send + Sync + 'static + Sized,
    {
        unimplemented!("ExternRef is not yet supported with wasm_c_api");
    }

    pub fn downcast<'a, T>(&self, _store: &'a impl AsStoreRef) -> Option<&'a T>
    where
        T: Any + Send + Sync + 'static + Sized,
    {
        unimplemented!("ExternRef is not yet supported in wasm_c_api");
    }

    pub(crate) fn vm_externref(&self) -> VMExternRef {
        unimplemented!("ExternRef is not yet supported in wasm_c_api");
    }

    pub(crate) unsafe fn from_vm_externref(
        _store: &mut impl AsStoreMut,
        _vm_externref: VMExternRef,
    ) -> Self {
        unimplemented!("ExternRef is not yet supported in wasm_c_api");

View on GitHub (pinned to 8c4b9ee9d3)

Solutions

Use the sys or js backend where externrefs are supported
Represent host values as i32 handles into a global registry instead of externrefs when targeting v8
Guard externref usage behind a backend capability check

Example fix

// before
let ext = ExternRef::new(&mut store, MyValue { .. }); // panics on v8
// after
let handle = REGISTRY.with(|r| r.borrow_mut().insert(MyValue { .. }));
Value::I32(handle)

Defensive patterns

Strategy: fallback

Validate before calling

fn externref_supported() -> bool {
    !cfg!(feature = "v8") // v8/wasm_c_api lacks ExternRef::new
}

Type guard

fn externref_supported() -> bool {
    !cfg!(feature = "v8")
}

Try / catch

if !externref_supported() {
    return Err(anyhow!("ExternRef unavailable on v8 backend; use handle registry"));
}
let ext = ExternRef::new(&mut store, value);

Prevention

Use i32 registry handles instead of ExternRef on v8 builds
Gate externref usage per backend with cargo features
Keep a backend-capability table in docs/tests for ExternRef, Exception, Table::copy

When it happens

Trigger: Calling `ExternRef::new(&mut store, value)` in any binary built with the v8 backend, for any value type.

Common situations: Passing opaque host objects (Rust structs) into wasm via externref globals/function params; code shared across sys/js/v8 backends where only v8 lacks support.

Related errors

AI-assisted analysis of wasmerio/wasmer@8c4b9ee9d3 (2026-09-01). Data as JSON: /api/errors/bcb4be0446fcdf1d. Report an issue: GitHub.