fluent/fluentd · error · Fluent::ConfigError

invalid number of workers (must be 1 or unspecified) with --

Error message

invalid number of workers (must be 1 or unspecified) with --no-supervisor: #{@system_config.workers}

What it means

Fluent::ConfigError raised in Supervisor#run_worker (lib/fluent/supervisor.rb:769) when fluentd is started with --no-supervisor (standalone worker mode) while workers is configured to anything other than 1. Standalone mode has no supervisor to spawn and manage multiple worker processes, so multi-worker configuration is incompatible with it.

Source

Thrown at lib/fluent/supervisor.rb:769

        supervise
      end
    end

    def options
      {
        'config_path' => @config_path,
        'pid_file' => @daemonize,
        'plugin_dirs' => @plugin_dirs,
        'log_path' => @log_path,
        'root_dir' => @system_config.root_dir,
      }
    end

    def run_worker
      Process.setproctitle("worker:#{@system_config.process_name}") if @process_name

      if @standalone_worker && @system_config.workers != 1
        raise Fluent::ConfigError, "invalid number of workers (must be 1 or unspecified) with --no-supervisor: #{@system_config.workers}"
      end

      if Fluent.windows? && @system_config.with_source_only
        raise Fluent::ConfigError, "with-source-only is not supported on Windows"
      end

      install_main_process_signal_handlers

      # This is the only log message for @standalone_worker
      $log.info "starting fluentd-#{Fluent::VERSION} without supervision", pid: Process.pid, ruby: RUBY_VERSION if @standalone_worker

      main_process do
        create_socket_manager if @standalone_worker
        if @standalone_worker
          ServerEngine::Privilege.change(@chuser, @chgroup)
          File.umask(@chumask.to_i(8))
        end
        MessagePackFactory.init(enable_time_support: @system_config.enable_msgpack_time_support)

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Remove --no-supervisor from the command line if you really need multiple workers
2. Or set workers to 1 (or delete the workers setting) in <system> or via --workers when keeping --no-supervisor
3. If you intended supervised multi-process operation, drop the flag and let the supervisor manage workers

Example fix

# before
$ fluentd --no-supervisor -c fluent.conf   # fluent.conf contains: <system> workers 4 </system>

# after (option 1)
$ fluentd -c fluent.conf                     # keep workers 4, supervised
# after (option 2)
$ fluentd --no-supervisor -c fluent.conf     # and change config to: <system> workers 1 </system>

# before launching:
workers = 4                      # parsed from your config <system> workers
no_supervisor = true             # from CLI flags
if no_supervisor && workers != 1
  abort '--no-supervisor requires workers == 1 (remove --no-supervisor or set workers 1)'
end

When it happens

Trigger: Starting fluentd with the --no-supervisor command-line flag together with --workers 2 (or <system> workers 4 in the config file). Any workers value != 1 (including nil-defaulted 1 is fine) triggers the error at run_worker time, right after process title setup.

Common situations: Copying a production multi-worker config into a systemd unit or Docker CMD that includes --no-supervisor; migrating from supervisord-style deployment where users add --no-supervisor to avoid ServerEngine supervision but forget to remove the workers setting.

Related errors

• <system> is duplicated. <system> should be only one
• time_type is :mixed but time_format and time_format_fallback
• specifying timezone requires time format
• Unsupported timezone '#{timezone}'
• When you set max_version, must set min_version together

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