Async::Container::Supervisor is replaced by Async::Service::

Error message

Async::Container::Supervisor is replaced by Async::Service::Supervisor, please update your service definition.

What it means

When a server worker starts, Falcon::Service::Server#run checks whether the environment evaluator still defines make_supervised_worker — the worker hook from the Async::Container::Supervisor era (lib/falcon/service/server.rb:107-112). If it does, Falcon warns that Async::Container::Supervisor is replaced by Async::Service::Supervisor, then invokes the legacy hook anyway for backward compatibility before building the server with make_server. The current preparation hook is prepare_worker! (which delegates to prepare!) from the async-service stack.

Source

Thrown at lib/falcon/service/server.rb:109

							server = run(instance, evaluator, listener)
							instance.name = format_title(evaluator, server)
							emit_running(instance, clock)
							
							instance.ready!
						end
					end
				end
			end
			
			# Run the service logic.
			#
			# @parameter instance [Object] The container instance.
			# @parameter evaluator [Environment::Evaluator] The environment evaluator.
			# @parameter listener [Falcon::Listener] The listener used by this worker.
			# @returns [Falcon::Server] The server instance.
			def run(instance, evaluator, listener = @listener)
				if evaluator.respond_to?(:make_supervised_worker)
					Console.warn(self, "Async::Container::Supervisor is replaced by Async::Service::Supervisor, please update your service definition.")
					
					evaluator.make_supervised_worker(instance).run
				end
				
				server = evaluator.make_server(listener.endpoint)
				
				Async do |task|
					server.run
					
					task.children&.each(&:wait)
				end
				
				server
			end
			
			# Format the process title with server statistics.
			#
			# @parameter evaluator [Environment::Evaluator] The environment evaluator.

View on GitHub (pinned to 5107b0713f)

Solutions

Remove make_supervised_worker from the environment and implement prepare_worker!(instance, listener) (typically delegating to prepare!) for custom worker setup
Move supervision to Async::Service::Supervisor in the services definition and align the Gemfile on the async-service stack
Until migrated, the warning is cosmetic — falcon still runs the legacy hook, so behaviour is unchanged

Example fix

# before: legacy hook, warns on every worker start
class MyAppEnvironment
  def make_supervised_worker(instance)
    Async::Container::Supervisor.new(instance).tap(&:run)
  end
end

# after: Async::Service based preparation
class MyAppEnvironment
  include Falcon::Environment::Server # provides prepare_worker! -> prepare!

  def prepare_worker!(instance, listener)
    prepare!(instance) # Async::Service::Supervisor handles supervision
  end
end

Defensive patterns

Strategy: validation

Validate before calling

# Preflight: refuse to deploy while the legacy supervisor hook is defined.
if environment.evaluator.respond_to?(:make_supervised_worker)
  abort 'Legacy Async::Container::Supervisor hook present; migrate to Async::Service (prepare_worker! / prepare!)'
end

Prevention

After upgrading falcon/async-service, grep environments and config/falcon.rb for make_supervised_worker and remove it
Implement prepare_worker!/prepare! for custom worker preparation instead of supervisor hooks
Watch Console output during supervised starts — the warning fires once per worker

When it happens

Trigger: Starting a Falcon host with a custom service/environment definition that still defines make_supervised_worker(instance) returning an object responding to run — e.g. an environment written for older falcon that started an Async::Container::Supervisor inside each worker.

Common situations: Upgrading falcon/async-service while keeping an old config/falcon.rb or copied service definition; in-house supervised-worker setups (process restart policies, reload hooks) built on async-container; stale examples or documentation.

Related errors

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