{"record":{"id":"72aecaf070310da6","repo":"fluent/fluentd","slug":"unknown-kind-plugin-type-run-gem-search","errorCode":null,"errorMessage":"Unknown #{@kind} plugin '#{type}'. Run 'gem search -rd fluent-plugin' to find plugins","messagePattern":"Unknown #(.+?) plugin '#(.+?)'\\. Run 'gem search -rd fluent-plugin' to find plugins","errorType":"exception","errorClass":"Fluent::NotFoundPluginError","httpStatus":null,"severity":"critical","filePath":"lib/fluent/registry.rb","lineNumber":48,"sourceCode":"    end\n\n    attr_reader :kind, :paths, :map, :dir_search_prefix\n\n    def register(type, value)\n      type = type.to_sym\n      @map[type] = value\n    end\n\n    def lookup(type)\n      type = type.to_sym\n      if value = @map[type]\n        return value\n      end\n      search(type)\n      if value = @map[type]\n        return value\n      end\n      raise NotFoundPluginError.new(\"Unknown #{@kind} plugin '#{type}'. Run 'gem search -rd fluent-plugin' to find plugins\",\n                                    kind: @kind, type: type)\n    end\n\n    def reverse_lookup(value)\n      @map.each do |k, v|\n        return k if v == value\n      end\n      nil\n    end\n\n    def search(type)\n      # search from additional plugin directories\n      if @dir_search_prefix\n        path = \"#{@dir_search_prefix}#{type}\"\n        files = @paths.filter_map { |lp|\n          lpath = File.expand_path(File.join(lp, \"#{path}.rb\"))\n          File.exist?(lpath) ? lpath : nil\n        }","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/fluent/fluentd/blob/dd45c6e18dc7be33b5e5a0f0767bf46307ff5626/lib/fluent/registry.rb#L30-L66","documentation":"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.","triggerScenarios":"@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.","commonSituations":"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).","solutions":["Fix typos in the @type value first - compare with the plugin README's registered name","Install the plugin: fluent-gem install fluent-plugin-<name> (or add it to the Gemfile and run bundle)","Verify visibility under the same environment: fluent-gem list | grep fluent-plugin, then run fluentd --dry-run -c <config>","For local plugins, add their directory with -p /path/to/plugins or the FLUENT_PLUGIN environment variable"],"exampleFix":"# before\n<match app.**>\n  @type s3_typo\n</match>\n\n# after\n<match app.**>\n  @type s3\n</match>\n# and, if the plugin is not built in:\n#   fluent-gem install fluent-plugin-s3","handlingStrategy":"try-catch","validationCode":"# validate the whole config (and plugin availability) before boot:\n#   fluentd --dry-run -c /etc/fluent/fluent.conf","typeGuard":null,"tryCatchPattern":"begin\n  Fluent::Plugin.new_output(type)\nrescue Fluent::NotFoundPluginError => e\n  $stderr.puts \"#{type} plugin missing - install with: fluent-gem install fluent-plugin-#{type}\"\n  raise\nend","preventionTips":["Run fluentd --dry-run in CI for every config change","Pin plugin gems in the Gemfile used to launch fluentd so environments match","Double-check @type spellings against each plugin's README"],"tags":["fluentd","plugin","registry","not-found","config"],"backgroundTag":"plugin-not-found","analyzedSha":"dd45c6e18dc7be33b5e5a0f0767bf46307ff5626","analyzedAt":"2026-08-21T16:22:07.332Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}