{"record":{"id":"8b13d2bb344c5995","repo":"wasmerio/wasmer","slug":"headless-is-not-a-valid-runtime-to-instantiate-dir","errorCode":null,"errorMessage":"Headless is not a valid runtime to instantiate directly","messagePattern":"Headless is not a valid runtime to instantiate directly","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"lib/cli/src/backend.rs","lineNumber":721,"sourceCode":"\n                if let Some(p) = &runtime_opts.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                    }\n                }\n\n                let engine = wasmer_compiler::EngineBuilder::new(config)\n                    .set_features(Some(supported_features))\n                    .set_target(Some(target.clone()))\n                    .engine()\n                    .into();\n                Ok(engine)\n            }\n            #[cfg(feature = \"v8\")]\n            Self::V8 => Ok(wasmer::v8::V8::new().into()),\n            Self::Headless => bail!(\"Headless is not a valid runtime to instantiate directly\"),\n            #[allow(unreachable_patterns)]\n            _ => bail!(\"Unsupported backend type\"),\n        }\n    }\n\n    /// Check if this backend supports all the required WebAssembly features\n    #[allow(unreachable_code)]\n    pub fn supports_features(&self, required_features: &Features, target: &Target) -> bool {\n        // Map BackendType to the corresponding wasmer::BackendKind\n        let backend_kind = match self {\n            #[cfg(feature = \"singlepass\")]\n            Self::Singlepass => wasmer::BackendKind::Singlepass,\n            #[cfg(feature = \"cranelift\")]\n            Self::Cranelift => wasmer::BackendKind::Cranelift,\n            #[cfg(feature = \"llvm\")]\n            Self::LLVM => wasmer::BackendKind::LLVM,\n            #[cfg(feature = \"v8\")]\n            Self::V8 => wasmer::BackendKind::V8,","sourceCodeStart":703,"sourceCodeEnd":739,"githubUrl":"https://github.com/wasmerio/wasmer/blob/8c4b9ee9d33fb2068863fbb3d328683e7e6ff7f5/lib/cli/src/backend.rs#L703-L739","documentation":"Wasmer's Backend enum includes a Headless variant, but it is only an internal marker (a runtime without a compiler/JS host is not usable as a directly chosen engine). get_engine refuses to instantiate it and bails with this message. The library throws it to prevent users from selecting a pseudo-backend that has no concrete engine implementation.","triggerScenarios":"Calling Backend::Headless.get_engine() (the public helper) while the Headless variant of wasmer::Backend is selected.","commonSituations":"Passing 'headless' or 'js' as the backend/engine in CLI flags or config (e.g. --backend headless), or programmatically constructing Backend::Headless and then requesting an engine from it.","solutions":["Choose a concrete backend such as cranelift, llvm, singlepass, or v8 instead of headless.","If you need a compiler-less engine, use the dedicated headless engine API (e.g. wasmer::Engine::headless()) rather than Backend::Headless.get_engine().","Check how the backend is being parsed/configured and fix the invalid value."],"exampleFix":"// before\nlet engine = Backend::Headless.get_engine()?;\n// after\nlet engine = Backend::Cranelift.get_engine()?;","handlingStrategy":"validation","validationCode":"fn ensure_concrete_backend(b: &Backend) -> Result<(), String> {\n    match b {\n        Backend::Headless => Err(\"Headless is not a valid runtime to instantiate directly\".into()),\n        _ => Ok(()),\n    }\n}","typeGuard":"fn is_instantiable(b: &Backend) -> bool {\n    !matches!(b, Backend::Headless)\n}","tryCatchPattern":"match backend.get_engine() {\n    Ok(engine) => engine,\n    Err(e) if e.to_string().contains(\"Headless is not a valid runtime\") => {\n        // fall back to a concrete backend\n        Backend::Cranelift.get_engine()?\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Never pass 'headless' as a backend/engine selection in CLI flags or configs.","Use the dedicated headless engine API if you need a compiler-less engine.","Whitelist allowed backend values before handing user input to the backend enum."],"tags":["wasmer","backend","configuration","runtime"],"backgroundTag":"invalid-backend-runtime","analyzedSha":"8c4b9ee9d33fb2068863fbb3d328683e7e6ff7f5","analyzedAt":"2026-09-01T23:06:31.009Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}