Skip to content

Migrating from ngx_mruby 2.x to 3.0.0

This guide is for moving scripts, configurations and builds from ngx_mruby 2.x to ngx_mruby 3.0.0. Each change that it covers is described once, under Behavior changes: read before upgrading in the release notes of v3.0.0: what 2.x did, what 3.0.0 does, what is affected and what to do. This guide links to each of those entries and adds the steps and examples: how to find the scripts and builds that an entry affects, what a change looks like in a script, and how to check the result. Read the release notes of the 2.x releases newer than the version you run first (docs/releases).

ngx_mruby 2.x bundles mruby 3.3.0. The development line of ngx_mruby 3 bundles mruby 4.1.0-rc2, the second release candidate of mruby 4.1.0. The v3 plan (docs/proposals/v3-plan.md, section 7, decision 1) sets mruby 4.1.0 as the mruby of v3; the owner chose on 2026-10-29 to bundle 4.1.0-rc2 instead of waiting for the tag, and the development line moves to 4.1.0 when it is tagged. The entries of the bundled mruby are the changes that were found and measured for ngx_mruby, not a complete list. mruby’s own lists of user-visible changes are doc/mruby3.4.md, doc/mruby4.0.md and, for 4.1, NEWS.md in mruby/.

  1. Check how you build the module: Builds.
  2. Find the directives that 3.0.0 refuses or runs in more locations, and change them: Configurations.
  3. Find the scripts that an entry affects, and change them: Scripts.
  4. Update log parsers and alerts: Log monitoring.
  5. If you maintain an mrbgem or other C code that uses the mruby C API, check it: C extensions and mrbgems.
  6. Check the result: Checking the result.
  • Build with Ruby 3.0 or later: the build of the bundled mruby stops on Ruby 2.x (Building the bundled mruby needs Ruby 3.0 or later). ruby --version prints the version of the Ruby on PATH.

  • Build with OpenSSL 3.0 or later, also for --with-openssl-src: Digest and SecureRandom of the default build come from gems of ngx_mruby that use its EVP_MAC and RAND_bytes APIs, and the build stops on OpenSSL 1.1.1, LibreSSL and BoringSSL (Digest and SecureRandom come from gems of ngx_mruby that need OpenSSL 3.0 or later). openssl version prints the version of the openssl command on PATH. The headers that the build uses can be of another version; a build with --with-openssl-src uses the headers of that source tree. On macOS, configure finds an OpenSSL of Homebrew under /opt/homebrew/opt/openssl or /usr/local/opt/openssl. For an OpenSSL 3 in another place, give its directories to the build, for example:

    export NGX_MRUBY_CFLAGS="-I$(brew --prefix openssl@3)/include"
    export NGX_MRUBY_LDFLAGS="-L$(brew --prefix openssl@3)/lib"

    A build_config.rb of your own that adds iij/mruby-digest or monochromegane/mruby-secure-random drops that line: the default gems have the same gem names.

  • With the build_config.rb of this release, rebuild the module; the bundled mruby is built with it (The bundled mruby is 4.1.0-rc2 instead of 3.3.0).

  • With a build_config.rb of your own (A build_config.rb of your own needs the core gem changes of mruby 4.1), find the lines that select core gems:

    grep -nE 'gembox|mruby-print|hal-posix|mruby-task|mruby-encoding|mruby-sleep|mruby-env|mruby-process|regexp|ngx_mruby_core_gems' build_config.rb

    To keep the core gems that the default build of ngx_mruby takes, copy NGX_MRUBY_CORE_GEMS and ngx_mruby_core_gems from the build_config.rb of this release, and call ngx_mruby_core_gems(conf) in place of conf.gembox 'full-core', as that file does. A build that needs fewer gems passes NGX_MRUBY_CORE_GEMS - %w[...]. To add a gem that the list leaves out, follow Core gems.

  • A build from a new checkout or a source archive gets the third-party mrbgems at the commits that build_config.rb.lock records (The third-party mrbgems are built at the commits that build_config.rb.lock records). In a tree that keeps mruby/build, remove it after a change of the lock, before the next build; otherwise rake stops with fatal: reference is not a tree when a clone does not have the new commit:

    rm -rf mruby/build

    To build a gem at another commit, follow Gem commits.

  • The default build no longer has the auto-ssl mrbgem and the classes that came with it (The default build leaves out the auto-ssl mrbgem and the classes that came with it). Scripts says how to find the scripts that use them.

  • No build of this release has the auto-ssl mrbgem, and the mruby build no longer reads NGX_MRUBY_AUTO_SSL (The auto-ssl mrbgem and NGX_MRUBY_AUTO_SSL are removed). Remove the variable from the environment of your builds; it has no effect. A server that gets its certificates with Nginx::SSL::ACME moves to nginx’s ngx_http_acme_module (nginx-acme) before the upgrade, or stays on 2.x. This finds the builds and the configurations that use them:

    grep -rnE 'NGX_MRUBY_AUTO_SSL|auto-ssl|Nginx::SSL::ACME' /path/to/build/scripts /path/to/nginx/conf
  • With ./configure --with-mruby-incdir, add <mruby_root>/build/host/include to the list of directories (Sources that include mruby.h need the generated headers).

  • With mrbgems of your own or of third parties, see C extensions and mrbgems.

  • nginx -t refuses a stream hook given twice in one context: look in each stream {} block and each of its server {} blocks for more than one of mruby_stream and mruby_stream_code, and in each stream {} block for more than one of mruby_stream_init and mruby_stream_init_code, of mruby_stream_init_worker and mruby_stream_init_worker_code, or of mruby_stream_exit_worker and mruby_stream_exit_worker_code. Keep the later directive of each, whose code ran on 2.x, and remove the others. nginx -t with the module of 3.0.0 names the second directive and its line:

    nginx: [emerg] "mruby_stream_code" directive is duplicated in /etc/nginx/nginx.conf:42

    One directive in the stream {} block and one in a server {} stay valid, and the server runs its own code. An alert that matches the mrb_string(...) load failed line of a stream directive whose file cannot be read matches mrb_file( as well: such a line is now mrb_file(PATH) open failed, as for the HTTP directives.

  • Output filters given at http or server level, or in a location, run in the locations below them: find the filter directives,

    grep -rnE 'mruby_output_(header|body)_filter' /etc/nginx

    and, for each, the block that holds it. A filter in the http {} block now runs in every location of every server, one in a server {} block in every location of the server, and one in a location in its nested locations and its if blocks, unless such a level gives a filter of the same kind of its own. Check that the filter can run for every response there, such as those of static files and upstreams, and move a filter that should run in some locations only into those locations. On 2.x, such a filter ran in none of these locations, except that one in a server {} block ran for the requests that matched no location.

Most entries name a method that you can search for. This finds them in the script files of a configuration (replace /path/to/scripts with the directories of the files that the *_handler directives name):

grep -rnE 'valid_encoding\?|allbits\?|anybits\?|nobits\?|remove_const|module_function|append_features|prepend_features|extend_object|singleton_method_added|\.(included|extended|prepended|inherited|method_added)\(|initialize_copy|respond_to_missing|respond_to\?|method_defined\?|method_missing|instance_methods|\.methods|iv_var|default_proc *=|FileTest|srand|Random\.new|Set\.new|Set\[|flatten_merge|RuntimeError|\.server *=|upstream_server *=|SystemStackError' /path/to/scripts

Search the inline code of the *_code directives in the nginx.conf files the same way. The items below say what to look for where a name is not enough, and show the change.

  • Hash#inspect and Hash#to_s use a new format: look for inspect, to_s, "#{...}" and sprintf or format with %s where the value can be a Hash or an Array of Hashes, and for => in the strings that a script or a test compares with.

    h = {"q" => "x"}
    Nginx.rputs h.to_s # 2.x: {"q"=>"x"} 3.0.0: {"q" => "x"}
    Nginx.rputs JSON.generate(h) # {"q":"x"} on both
  • Set#inspect and Set#to_s use a new format, and Set#flatten_merge is removed: the same search for a Set; set.to_a.join(",") gives the same string on both versions. The search above also finds flatten_merge: s.flatten_merge(t) becomes s.merge(Set.new(t).flatten), which gives on both versions the Set that s.flatten_merge(t) gave on 2.x, when t is a Set or an Array. s.merge(t.flatten) gives that Set only when t is a Set: for an Array t, Array#flatten flattens the Arrays inside it and keeps the Sets, where flatten_merge did the opposite:

    t = [2, Set.new([3])]
    Set.new([1]).flatten_merge(t) # 2.x: the Set of 1, 2 and 3 3.0.0: NoMethodError
    Set.new([1]).merge(Set.new(t).flatten) # the Set of 1, 2 and 3 on both
    Set.new([1]).merge(t.flatten) # the Set of 1, 2 and a Set that holds 3, on both
  • The message of NoMethodError names the class of the receiver: look for message next to rescue NoMethodError, and for undefined method in scripts.

    e.message == "undefined method 'foo'" # 2.x: true 3.0.0: false (the message goes on with " for NilClass")

    Rescue NoMethodError itself instead of comparing the message.

  • private and protected are enforced: look for calls, with a receiver other than self, of initialize, initialize_copy, respond_to_missing? and method_missing, of methods defined with def at the top level, of Kernel methods such as raise, sprintf and puts, and of methods below private or protected. In handler code, a method defined with def at the top level stays public, and calls of it with a receiver need no change (the proposal for #502, section 1.4). Calls on Kernel itself, such as Kernel.Integer(x), work on both versions; a Kernel method called on another object, such as 1.Integer("3"), raises. A protected method can be called with a receiver of the same class from a method of that class, as in CRuby. The search above finds instance_methods and methods, which leave private methods out. Checking respond_to? before such a call does not help: it returns true for a private method.

    class Router
    def call(r)
    pick(r) # no receiver: works on both
    end
    private
    def pick(r)
    r.uri
    end
    end
    Router.new.pick(r) # 2.x: works 3.0.0: NoMethodError
    Router.new.send(:pick, r) # works on both
    1.Integer("3") # 2.x: 3 3.0.0: NoMethodError (private method 'Integer' called for Integer)
    Kernel.Integer("3") # 3 on both
    Integer("3") # 3 on both
  • Module#remove_const, #private, #public, #protected, #module_function and the hooks are private: the search above finds most of them; look also for .private(, .public( and .protected( called on a class or module. For example, Foo.remove_const(:X) becomes Foo.send(:remove_const, :X).

  • Overrides of append_features, prepend_features and extend_object are not called: the search above finds them.

    module Plugin
    def self.append_features(base) # 3.0.0: never called, and no error
    base.extend(ClassMethods)
    super
    end
    end
    module Plugin
    def self.included(base) # called on both
    base.extend(ClassMethods)
    end
    end
  • allbits?, anybits? and nobits? are methods of Integer only: the search above finds them; x.allbits?(1) on a Float becomes x.to_i.allbits?(1).

  • FileTest is a module: the search above finds FileTest; only uses other than calls of its methods (FileTest.exist? and so on) need a change.

  • Assigning a constant in a method body is a SyntaxError: compiling the scripts finds it (see Checking the result).

    def setup
    Table = {} # 3.0.0: SyntaxError when the script is compiled
    Object.const_set(:Table, {}) # works on both
    end
  • "#@ivar", "#@@cvar" and "#$global" in a string interpolate the variable: look for #@ and #$ in double-quoted strings, heredocs and backquoted commands. The search also finds comments; read each line that it finds:

    grep -rnE '#[@$]' /path/to/scripts
    @id = 7
    Nginx.rputs "Ticket #@id" # 2.x: Ticket #@id 3.0.0: Ticket 7
    Nginx.rputs "Ticket \#@id" # Ticket #@id on both
    Nginx.rputs 'Ticket #@id' # Ticket #@id on both
  • An Array, a Hash or a Struct that holds itself can be compared: the search above finds SystemStackError. Only a script that rescues it around such a comparison needs a change.

  • Float values have no bit operations: look for <<, >>, &, |, ^ and ~ applied to a value that can be a Float: the result of to_f, of Float() or of arithmetic with a Float. The entry says how to get the number that 2.x gave.

    x = 1.5
    x << 1 # 2.x: 3 3.0.0: NoMethodError
    (x * 2).to_i # 3, the number of 2.x for x << 1
    x.to_i << 1 # 2, another number
  • String#valid_encoding? is not in the default build: the search above finds it. With the default build_config.rb of 2.x the method returned true for every string, so a check like this one never rejected a request and can be removed:

    Nginx.return Nginx::HTTP_BAD_REQUEST unless s.valid_encoding?
  • A seeded Random gives other numbers: the search above finds srand and Random.new; look also for tests that expect the numbers of a seeded generator.

  • Hash#default_proc= raises TypeError for an object that is not a Proc: the search above finds it; pass a Proc, for example h.default_proc = proc { |hash, key| hash[key] = [] }.

  • yield with keyword arguments to a block with keyword parameters works: nothing to change; a rescue ArgumentError that was there for this case is no longer reached.

  • A return inside a block or a for body of handler code ends the code: nothing to change in the scripts. A return inside a block or the body of for at the top level of handler code no longer raises LocalJumpError: the handler answers with the response that its code set before the return, where 2.x answered 500 (2.7.0 answered 200 with the output that a content handler had written before it). Log alerts on unexpected return (LocalJumpError) no longer fire for it.

  • A content handler that ends without output answers 200 with an empty body instead of 500: look at the mruby_content_handler and mruby_content_handler_code handlers that can end without writing a body: a handler that writes only when a condition holds, one that passes a value that can be "" or nil to Nginx.rputs, one that only sets response headers, and one that ends with Nginx.return Nginx::HTTP_OK or another status from 200 to 299 other than 201 and 204. On 3.0.0 they answer that status (200 when none is set) with Content-Length: 0; on 2.7.1 they answered 500. A handler that relied on the 500 sets the status that it means:

    body = Nginx::Request.new.headers_in["X-Answer"].to_s
    Nginx.rputs body # body "": 2.7.1 answers 500 3.0.0 answers 200 with Content-Length: 0
    if body.empty?
    Nginx.return Nginx::HTTP_NOT_FOUND # 404 on both
    else
    Nginx.rputs body
    end
  • An output body filter that ends with an empty body sends the response instead of closing the connection: nothing to change. A body filter that sets "" with Nginx::Filter#body= or #output, or leaves the body of a response without a body empty, sends the status with Content-Length: 0, where 2.7.2 and earlier closed the connection without a byte; 2.7.3 sends it as well.

  • The accessors of Nginx::Var become methods of Nginx::Var at their first use in a worker: the search above finds respond_to?, method_defined?, instance_methods and methods; look at the ones on an Nginx::Var or on Nginx::Var itself. Their answer for a variable now depends on whether the worker has served an access of the name before. Use exist? instead:

    v = Nginx::Var.new
    v.respond_to?(:request_method) # 2.x: false 3.0.0: true after the first v.request_method in the worker
    v.exist?("request_method") # true on both

    Also look for methods that the scripts define on Object or Kernel, for example with a def at the top level of handler code, whose name is also the name of a variable that a script reads with v.NAME. Once the accessor exists in a worker, v.NAME reads the variable instead of calling such a method. Rename the method. The search also finds method_missing: a script that wraps Nginx::Var#method_missing, for example with a module prepended to Nginx::Var whose method_missing calls super, sees only the first access of a name that gets an accessor. Move what the wrapper does to the code that reads the variable.

  • Nginx::Connection, Nginx::Server and Nginx::Request read their variables without calling Nginx::Var: look for methods that a script defines on Nginx::Var (class Nginx::Var, Nginx::Var.class_eval, define_method) and for iv_var, which the search above finds. A method of Nginx::Var no longer changes what Nginx::Connection#remote_ip and the other methods of the entry return; define the method on their class instead, in mruby_init_code, which runs once when nginx reads the configuration. Handler code runs on every request in the same mrb_state, so there the second alias_method would make nginx_remote_ip a copy of the new remote_ip, which then calls itself:

    mruby_init_code '
    class Nginx::Connection
    alias_method :nginx_remote_ip, :remote_ip
    def remote_ip
    Nginx::Request.new.headers_in["X-Real-IP"] || nginx_remote_ip # works on both
    end
    end
    ';
  • Dir comes from mruby’s core gem, and a closed Dir raises IOError instead of RuntimeError: the search above finds RuntimeError; look at the ones that rescue an exception of a Dir that can be closed, or of Dir.open with a block that closes the Dir.

    d = Dir.open(path)
    d.close
    begin
    d.read
    rescue RuntimeError # 2.x: rescued 3.0.0: not rescued (IOError)
    end
    begin
    d.read
    rescue IOError, RuntimeError # rescued on both
    end
  • ENV comes from mruby’s core gem: ENV.to_hash is gone, and ENV is Enumerable, Process comes from mruby’s core gem: Process.fork, Kernel#fork and Kernel#system are gone, exit in a handler raises SystemExit instead of ending the worker process, sleep without an argument raises ArgumentError and The default build leaves out Vedis and Cache (mruby-vedis and mruby-localmemcache): this finds the calls that change:

    grep -rnE 'to_hash|fork|system|to_int|Status\.new|exit!|(^|[^_.])exit|sleep *($|[;)}])|Vedis|Cache\.new' /path/to/scripts
    ENV.to_hash # 3.0.0: NoMethodError
    ENV.to_h # 3.0.0: the Hash 2.x: NoMethodError
    ENV.keys.each_with_object({}) { |k, h| h[k] = ENV[k] } # the Hash on both
    exit # 2.x: ends the worker process 3.0.0: SystemExit, the handler answers 500
    Nginx.return Nginx::HTTP_SERVICE_UNAVAILABLE # 503 on both; the code then runs to its end
    sleep # 2.x: waits until a signal comes 3.0.0: ArgumentError

    Start other processes outside nginx instead of fork and system, and keep the data of Vedis and Cache in Redis or in a store of your own, or uncomment the gem’s line in build_config.rb.

  • Digest and SecureRandom come from gems of ngx_mruby that need OpenSSL 3.0 or later: this finds the calls whose result changes; look at the dup and clone of digest objects, the HMAC objects whose digest or hexdigest is called more than once, and the urlsafe_base64 calls with an argument.

    grep -rnE 'Digest::|\.dup|\.clone|urlsafe_base64|random_bytes' /path/to/scripts
    d = Digest::SHA256.new.update("ab")
    d.dup.update("c").hexdigest # 2.x: the SHA-256 of "c" 3.0.0: the SHA-256 of "abc"
    Digest::SHA256.new.update("c").hexdigest # the SHA-256 of "c" on both
    SecureRandom.urlsafe_base64(32).size # 2.x: 22 3.0.0: 43
    SecureRandom.urlsafe_base64.size # 22 on both
  • Nginx::Upstream#server= and Nginx::Stream::Connection#upstream_server= raise ArgumentError for a string that cannot be a server: the search above finds both setters and RuntimeError; look at the ones that rescue an exception of a setter.

    u = Nginx::Upstream.new "backend"
    begin
    u.server = "192.0.2.1:notaport"
    rescue RuntimeError # 2.x: rescued 3.0.0: not rescued (ArgumentError)
    end
    begin
    u.server = "192.0.2.1:notaport"
    rescue ArgumentError, RuntimeError # rescued on both
    end
  • Nginx::Upstream#server= raises ArgumentError for a host name instead of resolving it: the search above finds the setter; look at what the script gives it, also when the script reads the value from a request or a file.

    u.server = "localhost:8080" # 2.x: resolved while the worker waits 3.0.0: ArgumentError
    u.server = "127.0.0.1:8080" # works on both

    Write an IPv4 address as four decimal numbers: 127.1 raises as well. For a name that does not change while nginx runs, write it in the server line of the upstream {} block and do not call the setter. nginx uses all the addresses of such a name: when it has more than one, Nginx::Upstream.new raises RuntimeError for that upstream, so remove that call too, or write an IP address in the server line. A name that does not resolve stops nginx at start.

  • The default build leaves out the auto-ssl mrbgem and the classes that came with it: this finds the constants and the two Dir methods that the default build no longer has:

    grep -rnE 'Nginx::SSL::ACME|Acme|HttpRequest|OpenSSL|PolarSSL|SimpleHttp|(^|[^:])HTTP::|Base64|Forwardable|FORWARDABLE|Tempfile|tmpdir' /path/to/scripts

    Base64, Dir.tmpdir and Dir.mktmpdir have replacements in the default build:

    Base64.encode(s) # 3.0.0: NameError (uninitialized constant Base64)
    [s].pack('m0') # the same string on both
    Base64.decode(b) # 3.0.0: NameError
    b.unpack1('m') # the same string on both
    Dir.tmpdir # 3.0.0: NoMethodError
    ENV['TMPDIR'] || '/tmp' # works on both

    For Dir.mktmpdir, see The auto-ssl mrbgem and the classes that came with it. The other constants need a conf.gem line of your own.

  • An access or post_read handler that waits in Nginx::Async.sleep ends as without the wait: look for Nginx::Async.sleep in mruby_access_handler* and mruby_post_read_handler* code. Under satisfy any, an access handler that sleeps and then ends without a result now allows the request; one that should deny it returns the status after the sleep:

    Nginx::Async.sleep 100
    # 2.x: without a result, the request reached its content and the connection closed
    # 3.0.0: without a result, nginx allows the request under satisfy any
    Nginx.return Nginx::HTTP_FORBIDDEN unless allowed? # on both: denies under satisfy all; under satisfy any nginx tries the other access handlers
  • An access or post_read handler that writes output ends the request after the response: nothing to change. Such a handler answers once and nginx keeps the connection, where 2.x went on with the phases and closed it; log alerts on its header already sent lines no longer fire.

  • A handler that sets no result does not take the result of an earlier handler: look for a server rewrite, rewrite, post_read or access handler that calls Nginx.return for every request, for example mruby_server_rewrite_handler_code 'Nginx.return Nginx::DECLINED'. The later content handlers that can end without output and without a status, and the access handlers under satisfy any that can end without a result, no longer take that value; one that should go on returns it itself:

    # mruby_content_handler_code, on a server whose server rewrite handler returns Nginx::DECLINED
    Nginx.rputs body if body # no body: 2.x went on to the static module 3.0.0 answers 200 with Content-Length: 0
    Nginx.return Nginx::DECLINED unless body # goes on to the static module on both
  • An mruby_set handler that waits in Nginx::Async.sleep sets its variable, and the request goes on: look for Nginx::Async.sleep in mruby_set and mruby_set_code. Code that called Nginx.return after the sleep to end the request returns that status from a later handler, for example a rewrite handler that reads the variable.

  • A rewrite or server rewrite handler that ends without a result goes on to the next phase handler: look at the mruby_rewrite_handler* and mruby_server_rewrite_handler* handlers that can end without Nginx.return or with Nginx.return Nginx::OK. On 2.x nginx ended such a request without a response; on 3.0.0 it goes on to the content of the location. A handler that should end the request returns the status it means:

    # mruby_rewrite_handler_code
    Nginx::Var.new.set "backend", "a" # no result: 2.x sends no response 3.0.0 goes on
    Nginx.return Nginx::HTTP_FORBIDDEN if deny # 403 on both
  • Nginx::Async::HTTP.sub_request works in a content handler, also after Nginx::Async.sleep: look for a rescue of RuntimeError around sub_request in mruby_content_handler* code, and remove it; the call returns the response:

    Nginx::Async.sleep 100
    res = Nginx::Async::HTTP.sub_request "/backend" # 2.7.3: RuntimeError, 500 3.0.0: the response
    Nginx.rputs res.body
  • A handler that waits for Nginx::Async::HTTP.sub_request runs its code once and ends as without the wait: nothing to change for most scripts. An access or post_read handler that calls sub_request runs once for the request on 3.0.0; work that counted on the code running again after the subrequest goes after the call, where its response is available.

  • A UDP stream session runs its code once: datagrams that arrive while the code waits do not start it again: look for Nginx::Stream::Async.sleep in the code of listen ... udp servers. On 3.0.0 the code runs once for the session; datagrams that arrive during the sleep do not start it again.

  • A stream session that waits when worker_shutdown_timeout expires ends then: nothing to change; with worker_shutdown_timeout, a stream session whose code still sleeps when the timeout expires ends without the code after the sleep.

  • Nginx.redirect with a local URI takes effect when the handler ends: look for Nginx.redirect with a path in the handlers. On 3.0.0 the code after the call runs before the target; its output and its status are not sent, while the response headers that it sets and the arguments of the request that it changes reach the target:

    Nginx.redirect "/backend"
    Nginx.rputs "fallback" # 2.x: sent with the answer of /backend 3.0.0: not sent, warn line
    return # leave the handler when the code after the call should not run
  • Nginx.rputs, Nginx.echo, Nginx.redirect and Nginx::Filter#body= raise TypeError when to_s of the argument does not return a String: look for calls of these methods and of Nginx::Filter#output with an argument that is not a String, and pass a String, nil or a value whose to_s returns a String instead.

  • Nginx::Async::HTTP.sub_request raises a RuntimeError in an mruby_set handler: look for Nginx::Async::HTTP.sub_request in mruby_set and mruby_set_code. Call it in a rewrite or access handler, which waits for the subrequest, and set the variable there with Nginx::Var#set.

  • An mruby_set value that cannot be converted to a String answers 500: look for mruby_set and mruby_set_code whose code can return a value that is not a String, and return a String instead.

  • Nginx.redirect with a local URI raises a RuntimeError in a log handler: look for Nginx.redirect with a path in the code of mruby_log_handler and mruby_log_handler_code, and move the call to a rewrite, access or content handler.

  • Output is sent with the status that the handler set, and error_page does not apply to it: look for Nginx.return, Nginx.send_header and Nginx.status_code= before and after Nginx.rputs or Nginx.echo in the handlers, and for error_page in the locations of those handlers. On 3.0.0 the output goes out with the status, and an error_page for that status does not apply:

    # 2.x: nginx's 401 page, or the page of an error_page for 401 3.0.0: 401 with the JSON
    Nginx.rputs '{"error":"no key"}'
    Nginx.return Nginx::HTTP_UNAUTHORIZED

    Without the Nginx.rputs, both versions answer nginx’s 401 page or the page of the error_page, so a handler that relied on them sets the status without output. After output, 301, 302, 303, 307 and 308 get no Location unless the script sets it with Nginx::Headers_out, and a status below 200 answers 500. A status set before the first output follows the same rule on 3.0.0, where 2.x sent the output with 200: a handler that means 200 calls Nginx.return Nginx::HTTP_OK after the output. Nginx::HTTP_CLOSE (444) with output, before or after it, sends nothing and closes the connection, as 2.x does for 444 after the output; 2.x sent output written after 444 with 200.

  • Methods that have no effect in a handler raise a RuntimeError there: look in the code of mruby_log_handler*, mruby_output_header_filter*, mruby_output_body_filter*, mruby_set and mruby_set_code for the methods of the rows below whose handler is in the third column, and for Nginx::Filter#body outside a body filter. On 3.0.0 each such call raises a RuntimeError that names the method and the handler, where 2.x returned without an effect on the response. Remove the call, or move it to a handler of the second column.

    Methods Where they work New raise
    Reading the request: the getters of Nginx::Request, Nginx::Headers_in#[], the reads of Nginx::Var, Nginx::Connection, the getters of Nginx::Server every handler and filter of a request none
    Changing the request: uri=, args=, method=, request_line=, Nginx::Headers_in#[]= and #delete mruby_set handlers, the post_read, server rewrite, rewrite, access and content handlers log handlers, header and body filters
    Assigning variables: Nginx::Var#NAME=, #set every handler and filter of a request none
    The response head: Nginx::Headers_out#[]= and #delete, Nginx.status_code=, Nginx.return and Nginx.send_header with a status, content_type= every handler and filter of a request but a log handler, while nginx has not sent the response header log handlers, and the other handlers after the response header is sent
    Output: Nginx.rputs, Nginx.echo the post_read, server rewrite, rewrite, access and content handlers, and body filters mruby_set handlers, log handlers, header filters
    The body of a body filter: Nginx::Filter#body, #body=, #output body filters #body elsewhere (#body= and #output raised there before)

    A log handler that passes a value to access_log assigns a variable with Nginx::Var, which works there:

    # in mruby_log_handler_code
    Nginx::Request.new.headers_out["X-Cost"] = cost # 2.x: no effect 3.0.0: RuntimeError
    Nginx::Var.new.cost = cost.to_s # both: access_log writes $cost
  • Nginx.redirect with a local URI raises a RuntimeError in mruby_set handlers and output filters: look for Nginx.redirect with a path in the code of mruby_set, mruby_set_code, mruby_output_header_filter* and mruby_output_body_filter*. On 3.0.0 the call raises a RuntimeError and makes no internal redirect, where 2.x ran the handlers of the other location inside the call. Move the call to a rewrite or access handler, where the redirect takes effect when the handler ends:

    # in mruby_set_code: 2.x: the redirect runs inside the call 3.0.0: RuntimeError, the variable is empty
    Nginx.redirect "/backend"
    # in mruby_rewrite_handler_code: the redirect takes effect when the handler ends, on 3.0.0
    Nginx.redirect "/backend"
  • Assigning a variable that nginx does not know, or does not let scripts change, raises: look for assignments with Nginx::Var (v.<name> = and set), and for the error lines is not found, not changeable and is not assinged of ngx_mrb_var_set_vector and ngx_mrb_var_set_func in the error.log of a 2.x server, which name the variables that such an assignment missed. On 3.0.0 the assignment raises NameError for a name that nginx does not know and RuntimeError for a variable that nginx does not let scripts change, or keeps no value of, where 2.x logged the line, returned nil and went on. Declare the variable with set or mruby_variable, or change the request with the setters of Nginx::Request and Nginx::Headers_in:

    v = Nginx::Var.new
    v.backend_url = "http://10.0.0.2/" # no set or mruby_variable declares $backend_url: 2.x: nil and an error line 3.0.0: NameError
    v.uri = "/other" # 2.x: nil and an error line 3.0.0: RuntimeError
    Nginx::Request.new.uri = "/other" # changes the URI on both

Dir.children, Dir#each_child, Dir.empty? and the methods of Enumerable on a Dir are new to scripts of 2.x; the first two leave out . and .. (see New features).

  • Exception#inspect, and so the mrb_run failed lines of error.log, use a new format: look in log parsers and alert rules for patterns on mrb_run failed lines, and for an exception class in parentheses at the end of a line.

    2.x: mrb_run failed: return 500 HTTP status code to client: error: boom (RuntimeError)
    3.0.0: mrb_run failed: return 500 HTTP status code to client: error: #<RuntimeError: boom>

    A pattern such as \(RuntimeError\)$ becomes #<RuntimeError: .

  • The message of NoMethodError names the class of the receiver: a pattern that ends at undefined method 'foo' no longer matches, because the message goes on with for <class>.

  • The messages logged while nginx reads the configuration are at the info level instead of notice: look in log parsers, alert rules and start scripts for mechanism enabled, compile info, target variable and ngx_mruby NOTICE. A start of nginx no longer writes these lines. nginx -t writes them at [info] to the startup log, which is the file given with -e, or else the error log path compiled into nginx (logs/error.log under the prefix by default). nginx copies a line of the startup log to the terminal only at warn and above, so the output of nginx -t does not show them.

    2.x, start: [notice] ... ngx_mruby/<version> (mruby/3.3.0) mechanism enabled in ...
    3.0.0, start: no such line
    3.0.0, nginx -t: [info] ... ngx_mruby/<version> (mruby/4.1.0) mechanism enabled in ... (startup log only)
    3.0.0, nginx -t -e stderr: [info] ... ngx_mruby/<version> (mruby/4.1.0) mechanism enabled in ... (terminal)

    A check that looks for one of these lines to see that the module is loaded runs nginx -t -e stderr and reads its output, or reads the startup log after nginx -t:

    nginx -t -e stderr 2>&1 | grep 'mechanism enabled'
  • Nginx.module_version and the mechanism enabled line give 3.0.0: look in scripts for Nginx.module_version, and in log parsers and alert rules for patterns on the version after ngx_mruby/. A comparison with a 2.x version, such as 2.7.1, or a pattern such as ngx_mruby/2\. no longer matches: 3.0.0 and its pre-releases give 3.0.0.

  • Syntax errors have the messages of Prism: a pattern on the text after syntax error, such as unexpected end of file, no longer matches. Match on SyntaxError and on the file and line instead.

    2.x: file (eval) line 1: syntax error, unexpected end of file
    3.0.0: file (eval) line 1: syntax error, unexpected end-of-input; expected an expression after the operator
  • A content handler that ends without output answers 200 with an empty body instead of 500: a pattern on response body is empty. return NGX_HTTP_INTERNAL_SERVER_ERROR no longer matches for the content handlers of the main request that end without output and with no status or a status from 200 to 299 that nginx does not answer by itself; it still matches for a status below 200, and for Nginx::HTTP_OK without output in the other handlers and in subrequests.

  • An output body filter that ends with an empty body sends the response instead of closing the connection: an alert on zero size buf in writer no longer fires for these responses, because nginx sends them.

  • access_log writes the variables that mruby log handlers set, and the status that was sent: find the mruby_log_handler and mruby_log_handler_code directives, the variables that their code assigns with Nginx::Var (v.NAME = ... and v.set "NAME", ...), and the log_format lines that name those variables. These lines now have the value that the log handler assigned, not the value from before it. A line that should keep the value from before the log handler names a copy that set makes in the location, which runs before the log phase:

    set $tokens "-";
    set $tokens_before_log $tokens;

    The status in the access log line is the status that was sent, also after a log handler raised; its mrb_run failed line still goes to error.log.

This finds the places in the C sources of a gem, or of a program that embeds mruby, that the entries below are about:

grep -rnE 'Data_Wrap_Struct|mrb_data_object_alloc|MRB_SET_INSTANCE_TT|MRB_ARGS_|mruby/ext/io\.h|mrb_alloca|mrb_open|allocf|MRB_NO_PRESYM' src/
  • An object of a class not declared MRB_TT_DATA cannot wrap C data: every class whose objects Data_Wrap_Struct or mrb_data_object_alloc creates needs the declaration after mrb_define_class:

    struct RClass *c = mrb_define_class(mrb, "Uname", mrb->object_class);
    MRB_SET_INSTANCE_TT(c, MRB_TT_DATA);
  • mruby checks the argument count of a C method against its spec: compare the spec of each mrb_define_method with what its mrb_get_args reads, in both directions. A method defined with MRB_ARGS_REQ(2) that reads one string (mrb_get_args(mrb, "S", &s)) and is called with one argument raises ArgumentError; define it with MRB_ARGS_REQ(1). A method defined with MRB_ARGS_REQ(1) that reads "o|o" and is called with two arguments raises too; define it with MRB_ARGS_ARG(1, 1).

  • Renamed headers and functions, and mrb_open() on failure:

    #include <mruby/io.h> /* was <mruby/ext/io.h> */
    void *buf = mrb_temp_alloc(mrb, size); /* was mrb_alloca(mrb, size) */
    mrb_state *mrb = mrb_open(); /* also in place of mrb_open_allocf(my_allocf, ud) */
    if (MRB_OPEN_FAILURE(mrb)) { /* ... */ } /* was: if (mrb == NULL) */
    /* a custom allocator, in place of mrb_default_allocf() or my_allocf */
    void *mrb_basic_alloc_func(void *ptr, size_t size) { /* ... */ }
  • Sources that include mruby.h need the generated headers: add -I<mruby>/build/host/include next to -I<mruby>/include where you compile such a source outside the mruby build.

  1. Compile every script with the mrbc of mruby 4.1.0-rc2. After a build of this release (sh build.sh or sh test.sh), mruby/bin/mrbc -c checks the syntax of a script: it prints Syntax OK, or the line of the error (for a constant assigned in a method body, <file>:2:3: syntax error, dynamic constant assignment) and exits with 1.

    for f in /path/to/scripts/*.rb; do mruby/bin/mrbc -c "$f" || echo "check: $f"; done
  2. Run the parts of a script that do not call the Nginx classes with both versions of mruby. The entries of mruby 4.0.0 were measured this way between 2026-10-04 and 2026-10-14: the same Ruby script ran with two mruby binaries, one built from the mruby tree of ngx_mruby 2.x (mruby 3.3.0) and one from mruby 4.0.0, in Docker (Ubuntu 22.04, gcc 11), with mruby’s default gembox or with the core gems of each version’s ngx_mruby build (full-core and iij/mruby-dir for 3.3.0, NGX_MRUBY_CORE_GEMS for 4.0.0). The entries of mruby 4.1.0-rc2 were measured on 2026-10-29 and 2026-10-31 with the mruby command of the host build of ngx_mruby, for 4.0.0 and for 4.1.0-rc2, and with the mruby command of mruby 3.3.0 built with its default gembox. The entries that say “the test suite of ngx_mruby saw the change” also changed a response or a log line of ngx_mruby itself. To do the same, copy the mruby/ directory of each version to a directory of its own, run rake MRUBY_CONFIG=default in each copy, and run your script with the bin/mruby of both copies. Do not run that rake in the mruby/ of an ngx_mruby checkout: it builds into mruby/build, where the build of the module keeps its mruby.

  3. Run the configuration with the module of this release on a test server, send the requests that reach each handler, and look in error.log for mrb_run failed lines with NoMethodError, TypeError, ArgumentError or SyntaxError.

These were checked the same way and did not change, so they need no check: String#size and #length count bytes (the mruby-encoding gem is not in the default build; see Core gems); the ArgumentError for a wrong number of arguments; Exception#message; Struct#inspect; Float#to_s; Integer division and modulo; Kernel#sleep and #usleep (from mruby-sleep).