{"record":{"id":"84eb7cbbaf717803","repo":"fluent/fluentd","slug":"unexpected-error-failed-to-read-data-from-plugin","errorCode":null,"errorMessage":"Unexpected error: failed to read data from plugin storage file: '#{@path}'","messagePattern":"Unexpected error: failed to read data from plugin storage file: '#(.+?)'","errorType":"exception","errorClass":"Fluent::ConfigError","httpStatus":null,"severity":"error","filePath":"lib/fluent/plugin/storage_local.rb","lineNumber":97,"sourceCode":"          end\n        end\n\n        if !@on_memory\n          dir = File.dirname(@path)\n          FileUtils.mkdir_p(dir, mode: @dir_mode) unless Dir.exist?(dir)\n          if File.exist?(@path)\n            raise Fluent::ConfigError, \"Plugin storage path '#{@path}' is not readable/writable\" unless File.readable?(@path) && File.writable?(@path)\n            begin\n              data = File.open(@path, 'r:utf-8:utf-8') { |io| io.read }\n              if data.empty?\n                log.warn \"detect empty plugin storage file during startup. Ignored: #{@path}\"\n                return\n              end\n              data = JSON.parse(data, Fluent::DEFAULT_JSON_PARSE_OPTIONS)\n              raise Fluent::ConfigError, \"Invalid contents (not object) in plugin storage file: '#{@path}'\" unless data.is_a?(Hash)\n            rescue => e\n              log.error \"failed to read data from plugin storage file\", path: @path, error: e\n              raise Fluent::ConfigError, \"Unexpected error: failed to read data from plugin storage file: '#{@path}'\"\n            end\n          else\n            raise Fluent::ConfigError, \"Directory is not writable for plugin storage file '#{@path}'\" unless File.stat(dir).writable?\n          end\n        end\n      end\n\n      def multi_workers_ready?\n        unless @multi_workers_available\n          log.error \"local plugin storage with multi workers should be configured to use directory 'path', or system root_dir and plugin id\"\n        end\n        @multi_workers_available\n      end\n\n      def load\n        return if @on_memory\n        return unless File.exist?(@path)\n        begin","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/fluent/fluentd/blob/dd45c6e18dc7be33b5e5a0f0767bf46307ff5626/lib/fluent/plugin/storage_local.rb#L79-L115","documentation":"This is the catch-all failure inside LocalStorage#configure's begin/rescue (storage_local.rb:95-97): any exception while opening or JSON.parse-ing the storage file — Errno::EACCES on open with wrong encoding flags, JSON::ParserError for malformed JSON, Encoding::UndefinedConversionError, or even the inner 'Invalid contents' ConfigError — is logged with the original error and re-raised as this Fluent::ConfigError. The actionable detail is in the preceding log.error line (path and the underlying error), not in this message.","triggerScenarios":"Storage file exists but contains malformed JSON (truncated by a crash mid-write, hand-edited and broken, or binary garbage); file exists but cannot be opened/read despite passing the readable? check (permissions changed racily, or an IO/encoding error); non-UTF-8 bytes that break the 'r:utf-8:utf-8' open.","commonSituations":"Power loss or SIGKILL leaving a partially written storage.json (no atomic rename landed); configuration-management tools templating the file badly; a path pointing at a directory's storage.json that was clobbered by logs; files transferred without binary-safe mode gaining a BOM or CRLF corruption.","solutions":["Read the preceding 'failed to read data from plugin storage file' log entry to identify the real underlying error (path: and error: fields)","If the file is corrupt JSON and the state is expendable, stop fluentd and delete/rename the file so a fresh one is created on next save","Repair the JSON offline if the state matters: validate with ruby -rjson -e 'JSON.parse(File.read(\"storage.json\"))' and fix until it parses to a Hash","If the cause is an encoding error, rewrite the file as UTF-8 (the code opens it with 'r:utf-8:utf-8')"],"exampleFix":"# before\n$ cat /var/log/fluent/storage.json\n{\"last_read\": 1234   # truncated: missing closing brace\n# => Unexpected error: failed to read data from plugin storage file: '...'\n\n# after\n$ cat /var/log/fluent/storage.json\n{\"last_read\": 1234}","handlingStrategy":"try-catch","validationCode":"require 'json'\npath = '/var/log/fluent/storage.json'\nbegin\n  JSON.parse(File.read(path, encoding: 'UTF-8')) if File.exist?(path) && !File.empty?(path)\nrescue JSON::ParserError, EncodingError, SystemCallError => e\n  raise \"storage file unreadable, restore or delete it: #{e}\"\nend","typeGuard":null,"tryCatchPattern":"begin\n  plugin.configure(conf)\nrescue Fluent::ConfigError => e\n  if e.message =~ /failed to read data from plugin storage file/\n    # the preceding log.error carries the original exception (parse/IO/encoding)\n    # decide: repair JSON, or archive + delete the file to reset state\n    exit 1\n  end\n  raise\nend","preventionTips":["Monitor for crashes/SIGKILLs of fluentd: partially written storage.json is the classic precursor","Validate state files after restoring from backup (JSON parses AND is a Hash) before starting fluentd","Transfer state files in binary-safe mode; ensure they stay UTF-8 without BOM"],"tags":["fluentd","storage","json","io-error","data-corruption","config-error","startup"],"backgroundTag":"invalid-json-format","analyzedSha":"dd45c6e18dc7be33b5e5a0f0767bf46307ff5626","analyzedAt":"2026-08-21T16:22:07.332Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}