fluent/fluentd · error · Fluent::ConfigError

Plugin '#{type}' does not support multi workers configuratio

Error message

Plugin '#{type}' does not support multi workers configuration (#{self.class})

What it means

With <system> workers N (N>1), every plugin in the config must answer multi_workers_ready? true; the check runs in Fluent::Plugin#configure after the plugin and its helpers are configured, using the effective system config (owner's or its own). A false answer raises ConfigError naming the plugin type and class. Plugins confined to a specific worker via a <worker N> block get workers overridden to 1 for that scope (see base.rb system_config_override), so they are exempt.

Source

Thrown at lib/fluent/plugin.rb:201

    end

    module FeatureAvailabilityChecker
      def configure(conf)
        super

        # extend plugin instance by this module
        # to run this check after all #configure methods of plugins and plugin helpers
        sysconf = if self.respond_to?(:owner) && owner.respond_to?(:system_config)
                    owner.system_config
                  elsif self.respond_to?(:system_config)
                    self.system_config
                  else
                    nil
                  end

        if sysconf && sysconf.workers > 1 && !self.multi_workers_ready?
          type = Fluent::Plugin.lookup_type_from_class(self.class)
          raise Fluent::ConfigError, "Plugin '#{type}' does not support multi workers configuration (#{self.class})"
        end
      end
    end
  end
end

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Confine the offending plugin to one worker with a <worker 0> block so its effective worker count is 1
2. Set <system> workers back to 1 (or a value the whole pipeline supports)
3. Upgrade the plugin to a multi-worker-capable version or replace it with one that supports workers
4. Split the workload: run the single-worker plugin in its own fluentd instance and forward to the multi-worker one

Example fix

# before
<system>
  workers 4
</system>
<source>
  @type my_single_worker_plugin
</source>

# after
<system>
  workers 4
</system>
<worker 0>
  <source>
    @type my_single_worker_plugin
  </source>
</worker>

# Pre-flight in a test: configure the plugin under a multi-worker system config
Fluent::SystemConfig.overwrite_system_config(Fluent::SystemConfig.new(workers: 4)) do
  plugin.configure(config_element)
end # raises here if the plugin is not multi-worker ready

When it happens

Trigger: <system> workers 4 combined with a single-worker-only plugin (typically some third-party inputs or plugins using non-multi-worker-safe resources); scaling a working single-worker config to multi-worker for the first time; adding a new source that never declared multi-worker support.

Common situations: Performance scaling attempts on multi-core hosts; third-party plugins predating multi-worker support; test configs running fine with workers 1 but failing in production tuned to N workers.

Related errors

• Unreloadable plugin: #{Fluent::Plugin.lookup_type_from_class
• Unknown #{@kind} plugin '#{type}'. Run 'gem search -rd fluen
• Missing '@type' parameter on <#{e.name}> directive
• 'format' parameter is required
• both of utc and localtime are specified, use only one of the

AI-assisted analysis of fluent/fluentd@dd45c6e18d (2026-08-21). Data as JSON: /api/errors/9dd4768a9e185b8e. Report an issue: GitHub.