fluent/fluentd · critical · Fluent::NotFoundPluginError

Unknown #{@kind} plugin '#{type}'. Run 'gem search -rd fluen

Error message

Unknown #{@kind} plugin '#{type}'. Run 'gem search -rd fluent-plugin' to find plugins

What it means

Raised as Fluent::NotFoundPluginError by Fluent::Registry#lookup, the machinery behind Fluent::Plugin.new_input/new_output/new_filter/new_parser/new_formatter. After a registry miss it runs search(): extra plugin directories registered with -p/FLUENT_PLUGIN, then $LOAD_PATH, then installed gems (fluentd's own gem excluded), then the built-in fluent/plugin/ tree. If nothing loads, the @kind (input, output, filter, parser, formatter, buffer, storage, ...) and type are reported with a hint to search for fluent-plugin gems.

Source

Thrown at lib/fluent/registry.rb:48

    end

    attr_reader :kind, :paths, :map, :dir_search_prefix

    def register(type, value)
      type = type.to_sym
      @map[type] = value
    end

    def lookup(type)
      type = type.to_sym
      if value = @map[type]
        return value
      end
      search(type)
      if value = @map[type]
        return value
      end
      raise NotFoundPluginError.new("Unknown #{@kind} plugin '#{type}'. Run 'gem search -rd fluent-plugin' to find plugins",
                                    kind: @kind, type: type)
    end

    def reverse_lookup(value)
      @map.each do |k, v|
        return k if v == value
      end
      nil
    end

    def search(type)
      # search from additional plugin directories
      if @dir_search_prefix
        path = "#{@dir_search_prefix}#{type}"
        files = @paths.filter_map { |lp|
          lpath = File.expand_path(File.join(lp, "#{path}.rb"))
          File.exist?(lpath) ? lpath : nil
        }

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Fix typos in the @type value first - compare with the plugin README's registered name
2. Install the plugin: fluent-gem install fluent-plugin-<name> (or add it to the Gemfile and run bundle)
3. Verify visibility under the same environment: fluent-gem list | grep fluent-plugin, then run fluentd --dry-run -c <config>
4. For local plugins, add their directory with -p /path/to/plugins or the FLUENT_PLUGIN environment variable

Example fix

# before
<match app.**>
  @type s3_typo
</match>

# after
<match app.**>
  @type s3
</match>
# and, if the plugin is not built in:
#   fluent-gem install fluent-plugin-s3

# validate the whole config (and plugin availability) before boot:
#   fluentd --dry-run -c /etc/fluent/fluent.conf

begin
  Fluent::Plugin.new_output(type)
rescue Fluent::NotFoundPluginError => e
  $stderr.puts "#{type} plugin missing - install with: fluent-gem install fluent-plugin-#{type}"
  raise
end

When it happens

Trigger: @type tai1 (typo) in <source>/<match>/<filter>; the third-party gem is not installed; the gem is installed in a different Ruby/gem set than the running fluentd (system ruby vs td-agent vs bundler); a local plugin file sitting in a directory that is not on any search path.

Common situations: Deploying a config to a host without the plugin gem; upgrading fluentd or switching to td-agent and losing the plugin; CI dry-run of a config whose Gemfile lacks the plugin; @type name not matching the registered name (e.g. s3 vs aws-s3 style naming).

Related errors

• Missing '@type' parameter on <#{e.name}> directive
• 'format' parameter is required
• both of utc and localtime are specified, use only one of the
• this plugin '#{self.class}' cannot handle arguments for <buf
• this plugin '#{self.class}' allows <buffer tag> only

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