diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb
index 0f2b71767d..44d7190ff3 100644
--- a/Library/Homebrew/formula.rb
+++ b/Library/Homebrew/formula.rb
@@ -69,9 +69,6 @@ class Formula
   extend Cachable
   extend Predicable
 
-  # @!method inreplace(paths, before = nil, after = nil)
-  # @see Utils::Inreplace.inreplace
-
   # The name of this {Formula}.
   # e.g. `this-formula`
   attr_reader :name
@@ -2201,6 +2198,30 @@ class Formula
   # end</pre>
   def install; end
 
+  # Sometimes we have to change a bit before we install. Mostly we
+  # prefer a patch, but if you need the {Formula#prefix prefix} of
+  # this formula in the patch you have to resort to `inreplace`,
+  # because in the patch you don't have access to any variables
+  # defined by the formula, as only `HOMEBREW_PREFIX` is available
+  # in the {DATAPatch embedded patch}.
+  #
+  # `inreplace` supports regular expressions:
+  # <pre>inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool"</pre>
+  #
+  # `inreplace` supports blocks:
+  # <pre>inreplace "Makefile" do |s|
+  #   s.gsub! "/usr/local", HOMEBREW_PREFIX.to_s
+  # end
+  # </pre>
+  #
+  # @see Utils::Inreplace.inreplace
+  # @api public
+  def inreplace(paths, before = nil, after = nil, audit_result = true) # rubocop:disable Style/OptionalBooleanParameter
+    super(paths, before, after, audit_result)
+  rescue Utils::Inreplace::Error
+    raise BuildError.new(self, "inreplace", paths, nil)
+  end
+
   protected
 
   def setup_home(home)
diff --git a/Library/Homebrew/test/formula_spec.rb b/Library/Homebrew/test/formula_spec.rb
index 928f53809b..8ad56f402d 100644
--- a/Library/Homebrew/test/formula_spec.rb
+++ b/Library/Homebrew/test/formula_spec.rb
@@ -576,6 +576,16 @@ describe Formula do
     end
   end
 
+  describe "::inreplace" do
+    specify "raises build error on failure" do
+      f = formula do
+        url "https://brew.sh/test-1.0.tbz"
+      end
+
+      expect { f.inreplace([]) }.to raise_error(BuildError)
+    end
+  end
+
   describe "::installed_with_alias_path" do
     specify "with alias path with nil" do
       expect(described_class.installed_with_alias_path(nil)).to be_empty
diff --git a/Library/Homebrew/utils/inreplace.rb b/Library/Homebrew/utils/inreplace.rb
index 35f7b19ae9..9763760258 100644
--- a/Library/Homebrew/utils/inreplace.rb
+++ b/Library/Homebrew/utils/inreplace.rb
@@ -10,7 +10,7 @@ module Utils
   module Inreplace
     extend T::Sig
 
-    # Error during replacement.
+    # Error during text replacement.
     class Error < RuntimeError
       def initialize(errors)
         formatted_errors = errors.reduce(+"inreplace failed\n") do |s, (path, errs)|
@@ -70,7 +70,7 @@ module Utils
         Pathname(path).atomic_write(s.inreplace_string)
       end
 
-      raise Error, errors unless errors.empty?
+      raise Utils::Inreplace::Error, errors if errors.present?
     end
 
     # @api private
@@ -86,7 +86,7 @@ module Utils
 
         contents.gsub!(old, new)
       end
-      raise Error, path => contents.errors unless contents.errors.empty?
+      raise Utils::Inreplace::Error, path => contents.errors if contents.errors.present?
 
       Pathname(path).atomic_write(contents.inreplace_string) unless read_only_run
       contents.inreplace_string