What causes "Stack size must be 1024-bit aligned" in wasmerio/wasmer?

Round the stack size up to the next multiple of 1024 before constructing the Linker

Stack size must be 1024-bit aligned

Error message

Stack size must be 1024-bit aligned

What it means

The linker's StackSize configuration must be a multiple of 1024 (the message says 1024-bit aligned, i.e. 128-byte / 1024-bit granularity). Stack regions in dynamically linked modules are laid out with this alignment so all side modules' stacks interleave correctly; an unaligned size would misalign subsequent stack allocations. The check panics at Linker::new time.

Source

Thrown at lib/wasix/src/state/linker/mod.rs:375

        let memory_type = main_module_memory_type(main_module)?;

        let memory = match memory {
            Some(m) => m,
            None => Memory::new(store, memory_type)?,
        };

        let stack_low = {
            let data_end = memory_base + dylink_section.mem_info.memory_size as u64;
            if !data_end.is_multiple_of(1024) {
                data_end + 1024 - (data_end % 1024)
            } else {
                data_end
            }
        };

        if !stack_size.is_multiple_of(1024) {
            panic!("Stack size must be 1024-bit aligned");
        }

        let stack_high = stack_low + stack_size;

        // Allocate memory for the stack. This does not need to go through the memory allocator
        // because it's always placed directly after the main module's data
        memory.grow_at_least(store, stack_high)?;

        trace!(
            memory_pages = ?memory.grow(store, 0).unwrap(),
            memory_base,
            stack_low,
            stack_high,
            "Memory layout"
        );

        let stack_pointer = create_main_stack_pointer_global(store, main_module, stack_high)?;

View on GitHub (pinned to 8c4b9ee9d3)

Solutions

Round the stack size up to the next multiple of 1024 before constructing the Linker
Validate/normalize any externally supplied stack size (env var, config file) before passing it in
Use the default stack size if unsure
Update your config templates that carry a non-1024-multiple stack size

Example fix

// before
let stack_size = std::env::var("STACK_SIZE").unwrap().parse().unwrap(); // e.g. 4097
let linker = Linker::new(&engine, StackSize(stack_size));
// after
let stack_size: u64 = std::env::var("STACK_SIZE").unwrap().parse().unwrap();
let stack_size = (stack_size + 1023) / 1024 * 1024; // round up to 1024
let linker = Linker::new(&engine, StackSize(stack_size));

Defensive patterns

Strategy: validation

Validate before calling

fn valid_stack_size(n: u64) -> bool { n > 0 && n % 1024 == 0 }
let n: u64 = env.parse().map_err(|_| "invalid STACK_SIZE")?;
let n = (n + 1023) / 1024 * 1024; // normalize before Linker::new
assert!(valid_stack_size(n));

Type guard

fn is_1024_aligned(n: u64) -> bool { n % 1024 == 0 }

Prevention

Always round externally supplied stack sizes up to a 1024 multiple
Validate env/config-derived numbers before constructing the Linker
Keep stack size settings consistent across services using this runtime
Document the 1024-alignment requirement next to the config knob

When it happens

Trigger: Calling Linker::new (or the config that feeds it) with stack_size not divisible by 1024, e.g. StackSize(4097) or a value parsed from an env var like RUST_LOG-style tuning knobs without validation.

Common situations: Setting StackSize via an environment variable or CLI flag with an arbitrary value; copying a stack size from a different runtime that uses different alignment; a typo such as 1023 or 1000.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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