diff --git a/CHANGELOG.md b/CHANGELOG.md
index 707a557dd78..27f966362b3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -76,6 +76,9 @@
 - Better error message for existed type constructor being used as value constructor.
   ([Jiangda Wang](https://github.com/Frank-III))
 
+- Print better error messages when shell commands used by compiler cannot be found.
+  ([wheatfox](https://github.com/enkerewpo))
+
 ### Build tool
 
 - Improved the error message you get when trying to add a package that doesn't
diff --git a/compiler-cli/src/beam_compiler.rs b/compiler-cli/src/beam_compiler.rs
index fe17db8efd0..974a2a314ea 100644
--- a/compiler-cli/src/beam_compiler.rs
+++ b/compiler-cli/src/beam_compiler.rs
@@ -4,6 +4,8 @@ use gleam_core::{
     paths, Result,
 };
 
+use crate::fs::get_os;
+
 use std::{
     collections::HashSet,
     io::{self, BufRead, BufReader, Write},
@@ -111,6 +113,7 @@ impl BeamCompiler {
             .map_err(|e| match e.kind() {
                 io::ErrorKind::NotFound => Error::ShellProgramNotFound {
                     program: "escript".into(),
+                    os: get_os(),
                 },
                 other => Error::ShellCommand {
                     program: "escript".into(),
diff --git a/compiler-cli/src/fs.rs b/compiler-cli/src/fs.rs
index 526e7632ac8..4f68d99e57a 100644
--- a/compiler-cli/src/fs.rs
+++ b/compiler-cli/src/fs.rs
@@ -1,6 +1,6 @@
 use gleam_core::{
     build::{NullTelemetry, Target},
-    error::{Error, FileIoAction, FileKind},
+    error::{parse_os, Error, FileIoAction, FileKind, OS},
     io::{
         BeamCompiler, CommandExecutor, Content, DirEntry, FileSystemReader, FileSystemWriter,
         OutputFile, ReadDir, Stdio, WrappedReader,
@@ -54,6 +54,32 @@ pub fn get_project_root(path: Utf8PathBuf) -> Result<Utf8PathBuf, Error> {
     })
 }
 
+pub fn get_os() -> OS {
+    parse_os(std::env::consts::OS, get_distro_str().as_str())
+}
+
+// try to extract the distro id from /etc/os-release
+pub fn extract_distro_id(os_release: String) -> String {
+    let distro = os_release.lines().find(|line| line.starts_with("ID="));
+    if let Some(distro) = distro {
+        let id = distro.split('=').nth(1).unwrap_or("").replace("\"", "");
+        return id;
+    }
+    "".to_string()
+}
+
+pub fn get_distro_str() -> String {
+    let path = Utf8Path::new("/etc/os-release");
+    if std::env::consts::OS != "linux" || !path.exists() {
+        return "other".to_string();
+    }
+    let os_release = read(path);
+    match os_release {
+        Ok(os_release) => extract_distro_id(os_release),
+        Err(_) => "other".to_string(),
+    }
+}
+
 /// A `FileWriter` implementation that writes to the file system.
 #[derive(Debug, Clone)]
 pub struct ProjectIO {
@@ -183,6 +209,7 @@ impl CommandExecutor for ProjectIO {
             Err(error) => Err(match error.kind() {
                 io::ErrorKind::NotFound => Error::ShellProgramNotFound {
                     program: program.to_string(),
+                    os: get_os(),
                 },
 
                 other => Error::ShellCommand {
diff --git a/compiler-cli/src/fs/tests.rs b/compiler-cli/src/fs/tests.rs
index e2ccc48514b..45d24ea88d6 100644
--- a/compiler-cli/src/fs/tests.rs
+++ b/compiler-cli/src/fs/tests.rs
@@ -99,3 +99,47 @@ fn is_gleam_path_test() {
         Utf8Path::new("/some-prefix/")
     ));
 }
+
+#[test]
+fn extract_distro_id_test() {
+    let os_release = "
+PRETTY_NAME=\"Debian GNU/Linux 12 (bookworm)\"
+NAME=\"Debian GNU/Linux\"
+VERSION_ID=\"12\"
+VERSION=\"12 (bookworm)\"
+VERSION_CODENAME=bookworm
+ID=debian
+HOME_URL=\"https://www.debian.org/\"
+";
+    assert_eq!(super::extract_distro_id(os_release.to_string()), "debian");
+
+    let os_release = "
+VERSION_CODENAME=jammy
+ID=ubuntu
+ID_LIKE=debian
+HOME_URL=\"https://www.ubuntu.com/\"
+";
+    assert_eq!(super::extract_distro_id(os_release.to_string()), "ubuntu");
+
+    assert_eq!(super::extract_distro_id("".to_string()), "");
+    assert_eq!(super::extract_distro_id("\n".to_string()), "");
+    assert_eq!(super::extract_distro_id("ID=".to_string()), "");
+    assert_eq!(super::extract_distro_id("ID= ".to_string()), " ");
+    assert_eq!(
+        super::extract_distro_id("ID= space test ".to_string()),
+        " space test "
+    );
+    assert_eq!(super::extract_distro_id("id=ubuntu".to_string()), "");
+    assert_eq!(
+        super::extract_distro_id("NAME=\"Debian\"\nID=debian".to_string()),
+        "debian"
+    );
+    assert_eq!(
+        super::extract_distro_id("\n\nNAME=\n\n\nID=test123\n".to_string()),
+        "test123"
+    );
+    assert_eq!(
+        super::extract_distro_id("\nID=\"id first\"\nID=another_id".to_string()),
+        "id first"
+    );
+}
diff --git a/compiler-core/src/error.rs b/compiler-core/src/error.rs
index 4ebc1f71d35..f3d70a875ba 100644
--- a/compiler-core/src/error.rs
+++ b/compiler-core/src/error.rs
@@ -18,7 +18,6 @@ use pubgrub::report::DerivationTree;
 use pubgrub::version::Version;
 use std::borrow::Cow;
 use std::collections::HashSet;
-use std::env;
 use std::fmt::{Debug, Display};
 use std::io::Write;
 use std::path::PathBuf;
@@ -32,6 +31,9 @@ pub type Name = EcoString;
 
 pub type Result<Ok, Err = Error> = std::result::Result<Ok, Err>;
 
+#[cfg(test)]
+pub mod tests;
+
 macro_rules! wrap_format {
     ($($tts:tt)*) => {
         wrap(&format!($($tts)*))
@@ -149,7 +151,7 @@ pub enum Error {
     Gzip(String),
 
     #[error("shell program `{program}` not found")]
-    ShellProgramNotFound { program: String },
+    ShellProgramNotFound { program: String, os: OS },
 
     #[error("shell program `{program}` failed")]
     ShellCommand {
@@ -344,6 +346,37 @@ impl SmallVersion {
         }
     }
 }
+#[derive(Debug, Clone, Eq, PartialEq, Copy)]
+pub enum OS {
+    Linux(Distro),
+    MacOS,
+    Windows,
+    Other,
+}
+
+#[derive(Debug, Clone, Eq, PartialEq, Copy)]
+pub enum Distro {
+    Ubuntu,
+    Debian,
+    Other,
+}
+
+pub fn parse_os(os: &str, distro: &str) -> OS {
+    match os {
+        "macos" => OS::MacOS,
+        "windows" => OS::Windows,
+        "linux" => OS::Linux(parse_linux_distribution(distro)),
+        _ => OS::Other,
+    }
+}
+
+pub fn parse_linux_distribution(distro: &str) -> Distro {
+    match distro {
+        "ubuntu" => Distro::Ubuntu,
+        "debian" => Distro::Debian,
+        _ => Distro::Other,
+    }
+}
 
 impl Error {
     pub fn http<E>(error: E) -> Error
@@ -1018,9 +1051,45 @@ your app.src file \"{app_ver}\"."
                 }]
             }
 
-            Error::ShellProgramNotFound { program } => {
+            Error::ShellProgramNotFound { program , os } => {
                 let mut text = format!("The program `{program}` was not found. Is it installed?");
 
+                match os {
+                    OS::MacOS => {
+                        fn brew_install(name: &str, pkg: &str) -> String {
+                            format!("\n\nYou can install {} via homebrew: brew install {}", name, pkg)
+                        }
+                        match program.as_str() {
+                            "erl" | "erlc" | "escript" => text.push_str(&brew_install("Erlang", "erlang")),
+                            "rebar3" => text.push_str(&brew_install("Rebar3", "rebar3")),
+                            "deno" => text.push_str(&brew_install("Deno", "deno")),
+                            "elixir" => text.push_str(&brew_install("Elixir", "elixir")),
+                            "node" => text.push_str(&brew_install("Node.js", "node")),
+                            "bun" => text.push_str(&brew_install("Bun", "oven-sh/bun/bun")),
+                            "git" => text.push_str(&brew_install("Git", "git")),
+                            _ => (),
+                        }
+                    }
+                    OS::Linux(distro) => {
+                        fn apt_install(name: &str, pkg: &str) -> String {
+                            format!("\n\nYou can install {} via apt: sudo apt install {}", name, pkg)
+                        }
+                        match distro {
+                            Distro::Ubuntu | Distro::Debian => {
+                                match program.as_str() {
+                                    "elixir" => text.push_str(&apt_install("Elixir", "elixir")),
+                                    "git" => text.push_str(&apt_install("Git", "git")),
+                                    _ => (),
+                                }
+                            }
+                            Distro::Other => (),
+                        }
+                    }
+                    _ => (),
+                }
+
+                text.push('\n');
+
                 match program.as_str() {
                     "erl" | "erlc" | "escript" => text.push_str(
                         "
@@ -1029,23 +1098,36 @@ https://gleam.run/getting-started/installing/",
                     ),
                     "rebar3" => text.push_str(
                         "
-Documentation for installing rebar3 can be viewed here:
-https://gleam.run/getting-started/installing/",
+Documentation for installing Rebar3 can be viewed here:
+https://rebar3.org/docs/getting-started/",
                     ),
-                    _ => (),
-                }
-                match (program.as_str(), env::consts::OS) {
-                    // TODO: Further suggestions for other OSes?
-                    ("erl" | "erlc" | "escript", "macos") => text.push_str(
+                    "deno" => text.push_str(
                         "
-You can also install Erlang via homebrew using \"brew install erlang\"",
+Documentation for installing Deno can be viewed here:
+https://docs.deno.com/runtime/getting_started/installation/",
                     ),
-                    ("rebar3", "macos") => text.push_str(
+                    "elixir" => text.push_str(
                         "
-You can also install rebar3 via homebrew using \"brew install rebar3\"",
+Documentation for installing Elixir can be viewed here:
+https://elixir-lang.org/install.html",
+                    ),
+                    "node" => text.push_str(
+                        "
+Documentation for installing Node.js via package manager can be viewed here:
+https://nodejs.org/en/download/package-manager/all/",
+                    ),
+                    "bun" => text.push_str(
+                        "
+Documentation for installing Bun can be viewed here:
+https://bun.sh/docs/installation/",
+                    ),
+                    "git" => text.push_str(
+                        "
+Documentation for installing Git can be viewed here:
+https://git-scm.com/book/en/v2/Getting-Started-Installing-Git",
                     ),
                     _ => (),
-                };
+                }
 
                 vec![Diagnostic {
                     title: "Program not found".into(),
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_bun_linux_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_bun_linux_other.snap
new file mode 100644
index 00000000000..dcf78684aab
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_bun_linux_other.snap
@@ -0,0 +1,8 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `bun` was not found. Is it installed?
+
+Documentation for installing Bun can be viewed here:
+https://bun.sh/docs/installation/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_bun_linux_ubuntu.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_bun_linux_ubuntu.snap
new file mode 100644
index 00000000000..dcf78684aab
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_bun_linux_ubuntu.snap
@@ -0,0 +1,8 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `bun` was not found. Is it installed?
+
+Documentation for installing Bun can be viewed here:
+https://bun.sh/docs/installation/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_bun_macos_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_bun_macos_other.snap
new file mode 100644
index 00000000000..9b4ef605e02
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_bun_macos_other.snap
@@ -0,0 +1,10 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `bun` was not found. Is it installed?
+
+You can install Bun via homebrew: brew install oven-sh/bun/bun
+
+Documentation for installing Bun can be viewed here:
+https://bun.sh/docs/installation/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_deno_linux_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_deno_linux_other.snap
new file mode 100644
index 00000000000..0c2cf16c1af
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_deno_linux_other.snap
@@ -0,0 +1,8 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `deno` was not found. Is it installed?
+
+Documentation for installing Deno can be viewed here:
+https://docs.deno.com/runtime/getting_started/installation/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_deno_linux_ubuntu.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_deno_linux_ubuntu.snap
new file mode 100644
index 00000000000..0c2cf16c1af
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_deno_linux_ubuntu.snap
@@ -0,0 +1,8 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `deno` was not found. Is it installed?
+
+Documentation for installing Deno can be viewed here:
+https://docs.deno.com/runtime/getting_started/installation/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_deno_macos_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_deno_macos_other.snap
new file mode 100644
index 00000000000..48e866bf2cd
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_deno_macos_other.snap
@@ -0,0 +1,10 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `deno` was not found. Is it installed?
+
+You can install Deno via homebrew: brew install deno
+
+Documentation for installing Deno can be viewed here:
+https://docs.deno.com/runtime/getting_started/installation/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_elixir_linux_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_elixir_linux_other.snap
new file mode 100644
index 00000000000..2fe981688d5
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_elixir_linux_other.snap
@@ -0,0 +1,8 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `elixir` was not found. Is it installed?
+
+Documentation for installing Elixir can be viewed here:
+https://elixir-lang.org/install.html
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_elixir_linux_ubuntu.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_elixir_linux_ubuntu.snap
new file mode 100644
index 00000000000..6019639ee3a
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_elixir_linux_ubuntu.snap
@@ -0,0 +1,10 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `elixir` was not found. Is it installed?
+
+You can install Elixir via apt: sudo apt install elixir
+
+Documentation for installing Elixir can be viewed here:
+https://elixir-lang.org/install.html
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_elixir_macos_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_elixir_macos_other.snap
new file mode 100644
index 00000000000..4f02f37ff94
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_elixir_macos_other.snap
@@ -0,0 +1,10 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `elixir` was not found. Is it installed?
+
+You can install Elixir via homebrew: brew install elixir
+
+Documentation for installing Elixir can be viewed here:
+https://elixir-lang.org/install.html
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_erlc_linux_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_erlc_linux_other.snap
new file mode 100644
index 00000000000..c017a6c35bb
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_erlc_linux_other.snap
@@ -0,0 +1,8 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `erlc` was not found. Is it installed?
+
+Documentation for installing Erlang can be viewed here:
+https://gleam.run/getting-started/installing/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_erlc_linux_ubuntu.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_erlc_linux_ubuntu.snap
new file mode 100644
index 00000000000..c017a6c35bb
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_erlc_linux_ubuntu.snap
@@ -0,0 +1,8 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `erlc` was not found. Is it installed?
+
+Documentation for installing Erlang can be viewed here:
+https://gleam.run/getting-started/installing/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_erlc_macos_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_erlc_macos_other.snap
new file mode 100644
index 00000000000..45f6d31d26f
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_erlc_macos_other.snap
@@ -0,0 +1,10 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `erlc` was not found. Is it installed?
+
+You can install Erlang via homebrew: brew install erlang
+
+Documentation for installing Erlang can be viewed here:
+https://gleam.run/getting-started/installing/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_git_linux_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_git_linux_other.snap
new file mode 100644
index 00000000000..7634a2c6c2b
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_git_linux_other.snap
@@ -0,0 +1,8 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `git` was not found. Is it installed?
+
+Documentation for installing Git can be viewed here:
+https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_git_linux_ubuntu.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_git_linux_ubuntu.snap
new file mode 100644
index 00000000000..74a5275de1d
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_git_linux_ubuntu.snap
@@ -0,0 +1,10 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `git` was not found. Is it installed?
+
+You can install Git via apt: sudo apt install git
+
+Documentation for installing Git can be viewed here:
+https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_git_macos_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_git_macos_other.snap
new file mode 100644
index 00000000000..6d212e07323
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_git_macos_other.snap
@@ -0,0 +1,10 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `git` was not found. Is it installed?
+
+You can install Git via homebrew: brew install git
+
+Documentation for installing Git can be viewed here:
+https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_node_linux_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_node_linux_other.snap
new file mode 100644
index 00000000000..3ef46c88afc
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_node_linux_other.snap
@@ -0,0 +1,8 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `node` was not found. Is it installed?
+
+Documentation for installing Node.js via package manager can be viewed here:
+https://nodejs.org/en/download/package-manager/all/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_node_linux_ubuntu.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_node_linux_ubuntu.snap
new file mode 100644
index 00000000000..3ef46c88afc
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_node_linux_ubuntu.snap
@@ -0,0 +1,8 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `node` was not found. Is it installed?
+
+Documentation for installing Node.js via package manager can be viewed here:
+https://nodejs.org/en/download/package-manager/all/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_node_macos_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_node_macos_other.snap
new file mode 100644
index 00000000000..eed81934356
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_node_macos_other.snap
@@ -0,0 +1,10 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `node` was not found. Is it installed?
+
+You can install Node.js via homebrew: brew install node
+
+Documentation for installing Node.js via package manager can be viewed here:
+https://nodejs.org/en/download/package-manager/all/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_rebar3_linux_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_rebar3_linux_other.snap
new file mode 100644
index 00000000000..f2b79118537
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_rebar3_linux_other.snap
@@ -0,0 +1,8 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `rebar3` was not found. Is it installed?
+
+Documentation for installing Rebar3 can be viewed here:
+https://rebar3.org/docs/getting-started/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_rebar3_linux_ubuntu.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_rebar3_linux_ubuntu.snap
new file mode 100644
index 00000000000..f2b79118537
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_rebar3_linux_ubuntu.snap
@@ -0,0 +1,8 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `rebar3` was not found. Is it installed?
+
+Documentation for installing Rebar3 can be viewed here:
+https://rebar3.org/docs/getting-started/
diff --git a/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_rebar3_macos_other.snap b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_rebar3_macos_other.snap
new file mode 100644
index 00000000000..78ec9c211c2
--- /dev/null
+++ b/compiler-core/src/error/snapshots/gleam_core__error__tests__shell_program_not_found_rebar3_macos_other.snap
@@ -0,0 +1,10 @@
+---
+source: compiler-core/src/error/tests.rs
+expression: "err[0].text"
+---
+The program `rebar3` was not found. Is it installed?
+
+You can install Rebar3 via homebrew: brew install rebar3
+
+Documentation for installing Rebar3 can be viewed here:
+https://rebar3.org/docs/getting-started/
diff --git a/compiler-core/src/error/tests.rs b/compiler-core/src/error/tests.rs
new file mode 100644
index 00000000000..1c15349a5cf
--- /dev/null
+++ b/compiler-core/src/error/tests.rs
@@ -0,0 +1,37 @@
+use super::*;
+use insta::assert_snapshot;
+
+#[test]
+fn test_shell_program_not_found_error() {
+    let cmds = vec!["erlc", "rebar3", "deno", "elixir", "node", "bun", "git"];
+    let oses = vec!["macos", "linux"];
+    let distros = vec!["ubuntu", "other"];
+
+    for cmd in &cmds {
+        for os in &oses {
+            if os != &"linux" {
+                let err = Error::ShellProgramNotFound {
+                    program: cmd.to_string(),
+                    os: parse_os(os, "other"),
+                }
+                .to_diagnostics();
+                assert_snapshot!(
+                    format!("shell_program_not_found_{cmd}_{os}_other"),
+                    err[0].text
+                );
+            } else {
+                for distro in &distros {
+                    let err = Error::ShellProgramNotFound {
+                        program: cmd.to_string(),
+                        os: parse_os(os, distro),
+                    }
+                    .to_diagnostics();
+                    assert_snapshot!(
+                        format!("shell_program_not_found_{cmd}_{os}_{distro}"),
+                        err[0].text
+                    );
+                }
+            }
+        }
+    }
+}