socketry/falcon · info

`Falcon::Server.middleware` is deprecated, use `.rack_middle

Error message

`Falcon::Server.middleware` is deprecated, use `.rack_middleware` instead.

What it means

Falcon::Server.middleware is a deprecated compatibility alias that forwards to rack_middleware (lib/falcon/server.rb:21-25). Calling it still works, but it emits a Ruby deprecation warning — only when $VERBOSE is set — pointing at the new name. The rename reflects the split between rack_middleware, which wraps a Rack application via Protocol::Rack::Adapter, and protocol_middleware, which wraps a Protocol::HTTP middleware directly.

Source

Thrown at lib/falcon/server.rb:22

# Copyright, 2017-2026, by Samuel Williams.

require "async/http/server"

require "protocol/http/middleware/builder"
require "protocol/http/content_encoding"

require "async/http/cache"
require "async/utilization"
require_relative "body/request_finished"
require_relative "middleware/verbose"
require "protocol/rack"

module Falcon
	# A server listening on a specific endpoint, hosting a specific middleware.
	class Server < Async::HTTP::Server
		# @deprecated Use {rack_middleware} instead.
		def self.middleware(...)
			warn("`Falcon::Server.middleware` is deprecated, use `.rack_middleware` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
			
			return self.rack_middleware(...)
		end
		
		# Wrap a Rack application with the standard server middleware.
		# @parameter rack_app [Proc | Object] A rack application/middleware.
		# @parameter verbose [Boolean] Whether to add the {Middleware::Verbose} middleware.
		# @parameter cache [Boolean] Whether to add the {Async::HTTP::Cache} middleware.
		def self.rack_middleware(rack_app, verbose: false, cache: true)
			return self.protocol_middleware(::Protocol::Rack::Adapter.new(rack_app), verbose: verbose, cache: cache)
		end
		
		# Wrap a protocol application with the standard server middleware.
		# @parameter application [Protocol::HTTP::Middleware] The protocol application/middleware.
		# @parameter verbose [Boolean] Whether to add the {Middleware::Verbose} middleware.
		# @parameter cache [Boolean] Whether to add the {Async::HTTP::Cache} middleware.
		def self.protocol_middleware(application, verbose: false, cache: true)
			::Protocol::HTTP::Middleware.build do

View on GitHub (pinned to 5107b0713f)

Solutions

1. Replace calls: Falcon::Server.middleware(app) -> Falcon::Server.rack_middleware(app)
2. For Protocol::HTTP (non-Rack) applications use Falcon::Server.protocol_middleware(application)
3. If the call site is a dependency, upgrade that gem or report the rename upstream

Example fix

# before
middleware = Falcon::Server.middleware(rack_app, verbose: true, cache: true)
# warning: `Falcon::Server.middleware` is deprecated, use `.rack_middleware` instead.

# after
middleware = Falcon::Server.rack_middleware(rack_app, verbose: true, cache: true)

# Feature-detect the renamed class method before calling it.
def build_falcon_middleware(rack_app, **options)
  name = Falcon::Server.respond_to?(:rack_middleware) ? :rack_middleware : :middleware
  Falcon::Server.public_send(name, rack_app, **options)
end

When it happens

Trigger: Calling Falcon::Server.middleware(rack_app, verbose:, cache:) in initializers, service definitions, or gems written against older falcon; the warning text becomes visible when the process runs with warnings enabled (ruby -w, RUBYOPT=-W, or Warning[:deprecated] = true).

Common situations: Upgrading falcon to a release that introduced the rack_middleware/protocol_middleware split; third-party middleware gems, templates, or tutorials still using the old name; CI setups that escalate warnings (-W) or treat deprecations as failures.

Related errors

• Async::Container::Supervisor is replaced by Async::Service::
• Could not find config/serve.rb or config.ru in #{root}!
• Unsupported application configuration: #{path}!
• Unable to resolve #{hostname}!

AI-assisted analysis of socketry/falcon@5107b0713f (2026-08-23). Data as JSON: /api/errors/987c922bccbf1063. Report an issue: GitHub.