{"record":{"id":"5e2a95e8f67b0907","repo":"gleam-lang/gleam","slug":"beam-compiler-instance-exited-status","errorCode":null,"errorMessage":"BEAM compiler instance exited: {status}","messagePattern":"BEAM compiler instance exited: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"compiler-cli/src/beam_compiler.rs","lineNumber":45,"sourceCode":"    // A guard held for cleaning up the temporary file used to start the BEAM instance.\n    _source: tempfile::NamedTempFile,\n}\n\nimpl BeamCompilerInstance {\n    pub fn compile(\n        &mut self,\n        out: &Utf8Path,\n        lib: &Utf8Path,\n        modules: &HashSet<Utf8PathBuf>,\n        stdio: Stdio,\n    ) -> Result<Vec<String>, Error> {\n        // Check that the BEAM instance is still alive before attempting to use it.\n        let exit_status = self\n            .process\n            .try_wait()\n            .expect(\"access BEAM instance exit state\");\n        if let Some(status) = exit_status {\n            panic!(\"BEAM compiler instance exited: {status}\");\n        }\n\n        // Prepare work to send to the BEAM instance.\n        let args = format!(\n            \"{{\\\"{}\\\", \\\"{}\\\", [\\\"{}\\\"]}}\",\n            escape_path(lib),\n            escape_path(out.join(\"ebin\")),\n            modules\n                .iter()\n                .map(|module| escape_path(out.join(paths::ARTEFACT_DIRECTORY_NAME).join(module)))\n                .join(\"\\\", \\\"\")\n        );\n\n        tracing::debug!(args=?args, \"call_beam_compiler\");\n\n        writeln!(self.stdin.as_ref().expect(\"stdin present\"), \"{args}.\").map_err(|error| {\n            Error::ShellCommand {\n                program: \"escript\".into(),","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/gleam-lang/gleam/blob/15b07c783065c92bb016b1b74ed0995a5259850f/compiler-cli/src/beam_compiler.rs#L27-L63","documentation":"The long-lived persistent Erlang/BEAM compiler instance that gleam uses to compile projects has terminated before this compilation request was sent to it. The library deliberately panics rather than send work to a dead process, because compilation could not possibly succeed. This usually means the escript/node child process crashed, was killed (OOM, signal), or exited early due to a bad environment.","triggerScenarios":"Calling compile on a BeamCompiler whose child process has already exited; detected via process.try_wait() returning Some(status) at the start of compile.","commonSituations":"Running out of memory so the OS kills the BEAM VM; an incompatible or missing Erlang installation; the BEAM instance crashing on malformed input; reusing a compiler instance after a previous fatal failure; container/CPU limits terminating the subprocess.","solutions":["Re-run the build; a transient BEAM crash is usually resolved by a fresh compiler instance.","Check Erlang/OTP is installed and on PATH at a version gleam supports (gleam --version; erl -version).","Look for OOM-killer or signal kills of the escript process in system logs (dmesg / journalctl) and raise memory limits.","Update gleam to the latest version in case the BEAM instance crash is a known fixed bug.","If reproducible, capture the crashing input and file an issue at github.com/gleam-lang/gleam."],"exampleFix":"// before: reusing a cached compiler instance across builds\nlet compiler = cache.get_beam_compiler();\ncompiler.compile(lib)?;\n// after: recreate the instance when the previous one has exited\nlet mut compiler = BeamCompiler::new(...);\ncompiler.compile(lib)?;","handlingStrategy":"retry","validationCode":"// Check the BEAM instance is alive before compiling\nif let Some(status) = beam_compiler.process.try_wait().ok().flatten() {\n    eprintln!(\"BEAM instance already exited: {status}; recreating\");\n    beam_compiler = BeamCompiler::new(...)?;\n}","typeGuard":"fn is_alive(p: &mut Child) -> bool { matches!(p.try_wait(), Ok(None)) }","tryCatchPattern":"match beam_compiler.compile(lib) {\n    Ok(out) => out,\n    Err(e) if e.to_string().contains(\"BEAM compiler instance exited\") => {\n        let mut fresh = BeamCompiler::new(...)?;\n        fresh.compile(lib)?\n    }\n}","preventionTips":["Verify Erlang/OTP is installed and on PATH before running builds.","Run builds with adequate memory headroom; watch for OOM kills of the escript process.","Don't reuse compiler instances across builds after a failure; recreate them.","Keep gleam and OTP versions aligned and up to date."],"tags":["compiler","process","beam","erlang"],"backgroundTag":"module-init-failed","analyzedSha":"15b07c783065c92bb016b1b74ed0995a5259850f","analyzedAt":"2026-09-14T11:14:59.388Z","contentChangedAt":"2026-09-14T11:14:59.388Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}