{"record":{"id":"caf3b35434cff81a","repo":"wasmerio/wasmer","slug":"the-headless-engine-can-t-be-chosen","errorCode":null,"errorMessage":"The headless engine can't be chosen","messagePattern":"The headless engine can't be chosen","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"lib/cli/src/backend.rs","lineNumber":439,"sourceCode":"        let compiler_config = self.get_sys_compiler_config(backends.first().unwrap())?;\n        let default_features = compiler_config.default_features_for_target(&target);\n        let features = self.get_features(&default_features)?;\n        Ok(wasmer_compiler::EngineBuilder::new(compiler_config)\n            .set_features(Some(features))\n            .set_target(Some(target))\n            .engine()\n            .into())\n    }\n\n    #[allow(unused_variables)]\n    #[cfg(feature = \"compiler\")]\n    pub(crate) fn get_sys_compiler_config(\n        &self,\n        rt: &BackendType,\n    ) -> Result<Box<dyn CompilerConfig>> {\n        self.validate_profiler()?;\n        let compiler_config: Box<dyn CompilerConfig> = match rt {\n            BackendType::Headless => bail!(\"The headless engine can't be chosen\"),\n            #[cfg(feature = \"singlepass\")]\n            BackendType::Singlepass => {\n                let mut config = wasmer_compiler_singlepass::Singlepass::new();\n                if self.enable_experimental_unaligned_memory_accesses {\n                    config.allow_experimental_unaligned_memory_accesses(true);\n                }\n                if self.enable_verifier {\n                    config.enable_verifier();\n                }\n                if self.enable_nan_canonicalization {\n                    config.canonicalize_nans(true);\n                }\n                if let Some(p) = &self.profiler {\n                    match p {\n                        Profiler::Perfmap => config.enable_perfmap(),\n                        Profiler::Gdb => config.enable_debugger(Debugger::Gdb),\n                        Profiler::Lldb => config.enable_debugger(Debugger::Lldb),\n                    }","sourceCodeStart":421,"sourceCodeEnd":457,"githubUrl":"https://github.com/wasmerio/wasmer/blob/8c4b9ee9d33fb2068863fbb3d328683e7e6ff7f5/lib/cli/src/backend.rs#L421-L457","documentation":"BackendType::Headless is a placeholder meaning \"no compiler, deserialize precompiled artifacts\"; it is not a compiler that get_sys_compiler_config can produce a CompilerConfig for. Any attempt to fetch a compiler config for the headless backend bails immediately.","triggerScenarios":"Calling get_sys_compiler_config(rt) with rt == BackendType::Headless, typically via get_sys_compiler_engine_for_target when the chosen engine type is Headless.","commonSituations":"Passing --engine headless to a command that needs to compile (not just deserialize) a module; programmatically selecting the headless backend where a JIT engine is required; misconfigured runtime defaulting to headless.","solutions":["Use a compiling backend (cranelift, singlepass, or llvm) instead of headless for compilation paths","Only use the headless engine with precompiled .wasmu artifacts","Fix the default backend/engine selection in your configuration or launcher"],"exampleFix":"// before\nlet engine = get_engine(&BackendType::Headless, target, &opts)?;\n// after\nlet engine = get_engine(&BackendType::Cranelift, target, &opts)?;","handlingStrategy":"validation","validationCode":"if matches!(rt, BackendType::Headless) {\n    return Err(\"headless cannot compile; use cranelift/singlepass/llvm for compilation paths\");\n}","typeGuard":"fn is_compilable(rt: &BackendType) -> bool {\n    !matches!(rt, BackendType::Headless | BackendType::V8)\n}","tryCatchPattern":"match result {\n    Err(e) if e.to_string().contains(\"headless engine can't be chosen\") => {\n        retry_with_backend(BackendType::Cranelift)\n    }\n    other => other?,\n}","preventionTips":["Use Headless only for deserializing precompiled artifacts","Never set headless as the default engine for run/compile commands","Map headless requests to a JIT backend in wrapper tooling"],"tags":["cli","backend","headless","engine","config"],"backgroundTag":"invalid-backend-selection","analyzedSha":"8c4b9ee9d33fb2068863fbb3d328683e7e6ff7f5","analyzedAt":"2026-09-01T23:06:31.009Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}