fluent/fluentd · error · Fluent::ConfigError

<counter_client> is required in <system>

Error message

<counter_client> is required in <system>

What it means

Fluent::ConfigError raised by the counter plugin helper's counter_client_create. Plugins that use Fluent's shared counter/metrics feature connect to a central counter server as a client; the client's host/port/timeout are read from system_config.counter_client, which is only populated when a <counter_client> section exists inside <system> in fluent.conf (system_config.rb defines that section). Without it the helper refuses to build a client and fails during plugin startup.

Source

Thrown at lib/fluent/plugin_helper/counter.rb:25

#
#        http://www.apache.org/licenses/LICENSE-2.0
#
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS,
#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#    See the License for the specific language governing permissions and
#    limitations under the License.
#

require 'fluent/plugin'
require 'fluent/counter/client'

module Fluent
  module PluginHelper
    module Counter
      def counter_client_create(scope:, loop: Coolio::Loop.new)
        client_conf = system_config.counter_client
        raise Fluent::ConfigError, '<counter_client> is required in <system>' unless client_conf
        counter_client = Fluent::Counter::Client.new(loop, port: client_conf.port, host: client_conf.host, log: log, timeout: client_conf.timeout)
        counter_client.start
        counter_client.establish(scope)
        @_counter_client = counter_client
        counter_client
      end

      attr_reader :_counter_client

      def initialize
        super
        @_counter_client = nil
      end

      def stop
        super
        @_counter_client.stop
      end

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Add a <counter_client> section inside <system>, e.g. <system><counter_client>host 127.0.0.1 port 24321 timeout 2</counter_client></system>, and ensure a counter server is listening there
2. If shared counters are not needed, switch metrics in <system> to @type local or remove the plugin calling counter_client_create
3. Verify fluentd loads the config you edited: check the -c path and the startup log line showing the config file

Example fix

# before (fluent.conf)
<system>
  <metric>
    @type counter
  </metric>
</system>
# Error: <counter_client> is required in <system>

# after
<system>
  <metric>
    @type counter
  </metric>
  <counter_client>
    host 127.0.0.1
    port 24321
    timeout 2
  </counter_client>
</system>

# before calling counter_client_create
unless Fluent::Config.system_config.counter_client
  raise Fluent::ConfigError, 'add <counter_client> to <system> or disable counter metrics'
end
client = counter_client_create(scope: 'my_plugin')

begin
  @client = counter_client_create(scope: scope)
rescue Fluent::ConfigError => e
  log.warn "counter server unavailable: #{e.message}; counters disabled"
  @client = nil
end

When it happens

Trigger: A plugin including Fluent::PluginHelper::Counter (or a metrics plugin using @type counter in <system>) calls counter_client_create(scope: '...') while system_config.counter_client is nil, i.e. fluent.conf has no <system> block containing <counter_client>host/port/timeout</counter_client>.

Common situations: Enabling @type counter metrics in <system> but forgetting the <counter_client> block; copying a counter-based plugin snippet from docs into a minimal fluent.conf; running fluentd with a -c override so the edited <system> section is not the file actually loaded.

Related errors

• @type is required in <format>
• @type is required in <parse>
• unknown_key
• buffer path is not configured. specify 'path' in <buffer>
• regexp#{i} does not contain 2 parameters

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