[Bug] wasm-gc: "Invalid stub type" for closure parameters containing String or Array in FFI stubs

[bikallem]

Description

When a wasm-gc FFI stub function takes a closure (function type) as a parameter, the compiler rejects closures whose internal signature contains String, Array[T], or enum types with error [4042] Invalid stub type.

Closures passed to FFI stubs should be treated as opaque externref values on wasm-gc, regardless of their internal type signatures. The closure's parameter/return types are a MoonBit-level concern and should not affect the wasm import signature — the closure itself is just an externref.

Closures that work: those containing only #external types (externref) or wasm value types (Int, Double, UInt, etc.)

Closures that fail: those containing String, Array[T], or enum types as parameters or return types

Minimal Reproduction

moon.mod.json:

{
  "name": "blem/closure-stub-bug",
  "version": "0.1.0",
  "moonc-opt": "v0.8.1"
}

moon.pkg.json:

{
  "is-main": true,
  "supported-targets": ["wasm-gc"]
}

main.mbt:

#external
pub type Event

#external
pub type EventListener

// --- These work (externref or wasm value types inside closure) ---

fn ok_externref(callback : (Event) -> Unit) -> EventListener = "m" "a"
fn ok_no_args(callback : () -> Unit) -> EventListener = "m" "b"
fn ok_int(callback : (Int) -> Unit) -> EventListener = "m" "c"
fn ok_double(callback : (Double) -> Unit) -> EventListener = "m" "d"
fn ok_ret_externref(callback : (Event) -> Event) -> EventListener = "m" "e"

// --- These fail with [4042] "Invalid stub type" ---

fn fail_string_param(callback : (String) -> Unit) -> EventListener = "m" "f"
fn fail_string_return(callback : (Event) -> String) -> EventListener = "m" "g"
fn fail_array_param(callback : (Array[Event]) -> Unit) -> EventListener = "m" "h"

fn main {
  ignore(ok_externref)
  ignore(ok_no_args)
  ignore(ok_int)
  ignore(ok_double)
  ignore(ok_ret_externref)
  ignore(fail_string_param)
  ignore(fail_string_return)
  ignore(fail_array_param)
}

Actual behavior

$ moon build --target wasm-gc

Error: [4042]
 fn fail_string_param(callback : (String) -> Unit) -> EventListener = "m" "f"
                                 ────────┬───────
                                         ╰───────── Invalid stub type.

Error: [4042]
 fn fail_string_return(callback : (Event) -> String) -> EventListener = "m" "g"
                                  ────────┬────────
                                          ╰────────── Invalid stub type.

Error: [4042]
 fn fail_array_param(callback : (Array[Event]) -> Unit) -> EventListener = "m" "h"
                                ───────────┬──────────
                                           ╰──────────── Invalid stub type.

Expected behavior

All FFI stubs should compile successfully. The closure parameter is an externref on wasm-gc regardless of its internal type signature.

Environment

• moonc -v: v0.8.1+bd827dc85 (2026-02-09)
• moon version: moon 0.1.20260209 (b129ae2 2026-02-09)
• OS: Linux 6.18.7-arch1-1

[Guest0x0]

For Array, I think this is intended. For types with an undefined ABI, such as Array, passing a closure containing these types outside is meaningless because:

• the outside world cannot construct Array, because its ABI is undefined
• the outside world can neither obtain Array via other FFI, because passing Array directly in FFI is also forbidden, due to undefined ABI

On the other hand, String is indeed allowed in wasm-gc FFI. So the (Event) -> String example being rejected is indeed a bug. Will fix soon.

[Guest0x0]

The ABI of Array is undefined in wasm-gc because Array in MoonBit is an extensible (e.g. arr.push()) array type with extra structure. For FFI usage FixedArray (fixed length array, can still mutate elements) and ReadOnlyArray would be more suitable.

It seems that FixedArray and ReadOnlyArray is currently also forbidden in wasm-gc import, but I don't think this is necessary. Will try to relax this restriction.

[bikallem]

Thank you. I appreciate you looking into this. This and a couple other wasm-gc issues that I reported are preventing me from supporting wasm-gc backend in https://github.com/bikallem/webapi.

With regards to this issue - moonbit closures specifically, my haunch here is that the wasm-gc compiler is being overly restrictive for the wasm-gc backend. As this code shows - https://github.com/moonbitlang/moonbit-compiler/blob/main/src/typeutil.ml#L942 , other backends - js and c/native - completely skip this check_stub_type entirely. The entire check_stub_type validation (including is_simple_stub) only runs for the wasm and wasm-gc backends.

For the wasm (non-gc) backend, closures aren't externref — they need concrete representations, so validating their internal
types makes sense there. The is_simple_stub restrictions are appropriate for wasm.

The bug is specifically that wasm-gc gets the same restrictive validation as wasm, even though closures are externref on
wasm-gc. The top-level code already has wasm-gc exceptions (e.g., allowing String on wasm-gc imports at line 970), but
is_simple_stub was never given the same treatment.

I did an initial investigation at moonbitlang/moonbit-compiler#5 and the changes seems to fix the repro case above. However, I leave it to your good judgement to determine the validity of the fix.

[Guest0x0]

The fix of String in closure has already landed in the compiler, and should be available in the next release.

As for closure, in fact internally it is not externref, but rather some wasm-gc ref type (whose structure is subjected to future change due to optimization etc.). To convert closure to externref so that they can be used in FFI, a user-provided import moonbit:ffi.make_closure must be provided, which accepts the function pointer (as a funcref) and the capture data of the closure (as an opaque anyref). But this automatic conversion using moonbit:ffi.make_closure is done by the compiler, and the compiler cannot recursively insert the same conversion inside the parameters and return value of a closure, or even deeper. That's why the is_simple_stub restriction you see exists.

When passing callback outside MoonBit, it is actually easier to use the FuncRef[_] type, which is the type of capture-free function. FuncRef[_] directly correspond to funcref in wasm-gc, so there is less restriction on it (after the is_simple_stub problem is fixed in the next release). The downside, of course, is that you cannot capture local variables in FuncRef[_].

I guess you have probably already read https://docs.moonbitlang.com/en/latest/language/ffi.html, but more details on the moonbit:ffi.make_closure thing and FuncRef can be found there.

[bikallem]

The fix of String in closure has already landed in the compiler, and should be available in the next release.

Excellent! Is this in the moonbit nightly?

[Guest0x0]

The fix of String in closure has already landed in the compiler, and should be available in the next release.

Excellent! Is this in the moonbit nightly?

The fix for String and FuncRef[_] should be in MoonBit nightly already. And there is plan for a minor bug fix release in a day or two, where the fix is included.

[Guest0x0]

I think the fix is already in the latest stable release

[bikallem]

The fix of String in closure has already landed in the compiler, and should be available in the next release.

Excellent! Is this in the moonbit nightly?

The fix for String and FuncRef[_] should be in MoonBit nightly already. And there is plan for a minor bug fix release in a day or two, where the fix is included.

What about the ReadableArray and FixedArray, are they allowed in wasm-gc ffi stub now?

[Guest0x0]

What about the ReadableArray and FixedArray, are they allowed in wasm-gc ffi stub now?

Not yet, since this part is not a bug fix, but rather a feature enhancement. I'll review this before the next release.