{"record":{"id":"6caa301495c7189b","repo":"fluent/fluentd","slug":"counter-client-is-required-in-system","errorCode":null,"errorMessage":"<counter_client> is required in <system>","messagePattern":"<counter_client> is required in <system>","errorType":"exception","errorClass":"Fluent::ConfigError","httpStatus":null,"severity":"error","filePath":"lib/fluent/plugin_helper/counter.rb","lineNumber":25,"sourceCode":"#\n#        http://www.apache.org/licenses/LICENSE-2.0\n#\n#    Unless required by applicable law or agreed to in writing, software\n#    distributed under the License is distributed on an \"AS IS\" BASIS,\n#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n#    See the License for the specific language governing permissions and\n#    limitations under the License.\n#\n\nrequire 'fluent/plugin'\nrequire 'fluent/counter/client'\n\nmodule Fluent\n  module PluginHelper\n    module Counter\n      def counter_client_create(scope:, loop: Coolio::Loop.new)\n        client_conf = system_config.counter_client\n        raise Fluent::ConfigError, '<counter_client> is required in <system>' unless client_conf\n        counter_client = Fluent::Counter::Client.new(loop, port: client_conf.port, host: client_conf.host, log: log, timeout: client_conf.timeout)\n        counter_client.start\n        counter_client.establish(scope)\n        @_counter_client = counter_client\n        counter_client\n      end\n\n      attr_reader :_counter_client\n\n      def initialize\n        super\n        @_counter_client = nil\n      end\n\n      def stop\n        super\n        @_counter_client.stop\n      end","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/fluent/fluentd/blob/dd45c6e18dc7be33b5e5a0f0767bf46307ff5626/lib/fluent/plugin_helper/counter.rb#L7-L43","documentation":"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.","triggerScenarios":"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>.","commonSituations":"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.","solutions":["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","If shared counters are not needed, switch metrics in <system> to @type local or remove the plugin calling counter_client_create","Verify fluentd loads the config you edited: check the -c path and the startup log line showing the config file"],"exampleFix":"# before (fluent.conf)\n<system>\n  <metric>\n    @type counter\n  </metric>\n</system>\n# Error: <counter_client> is required in <system>\n\n# after\n<system>\n  <metric>\n    @type counter\n  </metric>\n  <counter_client>\n    host 127.0.0.1\n    port 24321\n    timeout 2\n  </counter_client>\n</system>","handlingStrategy":"validation","validationCode":"# before calling counter_client_create\nunless Fluent::Config.system_config.counter_client\n  raise Fluent::ConfigError, 'add <counter_client> to <system> or disable counter metrics'\nend\nclient = counter_client_create(scope: 'my_plugin')","typeGuard":null,"tryCatchPattern":"begin\n  @client = counter_client_create(scope: scope)\nrescue Fluent::ConfigError => e\n  log.warn \"counter server unavailable: #{e.message}; counters disabled\"\n  @client = nil\nend","preventionTips":["Pair @type counter metrics with a configured <counter_client> section","Run fluentd --dry-run -c fluent.conf in CI to catch missing <system> sections","Keep a checked-in fluent.conf template that includes the counter_client block when counters are enabled"],"tags":["fluentd","configuration","counter","metrics","plugin-helper"],"backgroundTag":"missing-config-section","analyzedSha":"dd45c6e18dc7be33b5e5a0f0767bf46307ff5626","analyzedAt":"2026-08-21T16:22:07.332Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}