fluent/fluentd · error · Fluent::ConfigError

in_debug_agent: `#{@unix_path}` is not writable

Error message

in_debug_agent: `#{@unix_path}` is not writable

What it means

The debug_agent input opens a DRb Unix socket at unix_path. During configure it checks Fluent::FileUtil.writable?(@unix_path); when that returns false it raises Fluent::ConfigError 'in_debug_agent: `<path>` is not writable'. The check covers a path on a directory without write permission for the fluentd user, a read-only filesystem, or SELinux/AppArmor denials, and fails before the agent starts.

Source

Thrown at lib/fluent/plugin/in_debug_agent.rb:42

      require 'drb/drb'
      require 'fluent/plugin/file_util'
      super
    end

    config_param :bind, :string, default: '127.0.0.1'
    config_param :port, :integer, default: 24230
    config_param :unix_path, :string, default: nil
    #config_param :unix_mode  # TODO
    config_param :object, :string, default: 'Fluent::Engine'

    def configure(conf)
      super
      if system_config.workers > 1
        @port += fluentd_worker_id
      end
      if @unix_path
        unless ::Fluent::FileUtil.writable?(@unix_path)
          raise Fluent::ConfigError, "in_debug_agent: `#{@unix_path}` is not writable"
        end
      end
    end

    def multi_workers_ready?
      @unix_path.nil?
    end

    def start
      super

      if @unix_path
        require 'drb/unix'
        uri = "drbunix:#{@unix_path}"
      else
        uri = "druby://#{@bind}:#{@port}"
      end
      log.info "listening dRuby", uri: uri, object: @object, worker: fluentd_worker_id

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Create the parent directory with correct ownership: mkdir -p /var/run/fluent && chown fluent:fluent /var/run/fluent.
2. Or point unix_path into a writable location such as /tmp/fluent-agent.sock or the fluentd home.
3. Or omit unix_path entirely to serve debug_agent over TCP on port 24230 (multi_workers_ready? requires unix_path nil).
4. On SELinux systems, adjust the context or policy for the socket path.

Example fix

# before
<source>
  @type debug_agent
  unix_path /var/run/fluent-agent.sock
</source>
# after
sudo mkdir -p /var/run/fluent && sudo chown fluent:fluent /var/run/fluent
# config:
<source>
  @type debug_agent
  unix_path /var/run/fluent/fluent-agent.sock
</source>

# preflight as the fluentd user
require 'fileutils'
path = '/var/run/fluent/fluent-agent.sock'
dir = File.dirname(path)
FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
abort "#{dir} not writable" unless File.writable?(dir)

begin
  Fluent::Plugin.new_input('debug_agent').configure(conf)
rescue Fluent::ConfigError => e
  abort "debug_agent config rejected: #{e.message}" # '... is not writable'
end

When it happens

Trigger: Configuring in_debug_agent with a unix_path whose parent directory the fluentd process cannot write to (commonly /var/run or /run owned by root), or a stale socket path on a read-only mount.

Common situations: Running fluentd as a non-root user with unix_path under /var/run; containers with read-only root filesystems; SELinux enforcing on RHEL-type systems; paths copied from root-run examples.

Related errors

• Cannot access pid file: #{pid_path}
• Cannot access directory for pid file: #{File.dirname(pid_pat
• staged meta file is broken. #{e.message}
• enqueued file chunk is empty
• enqueued meta file is broken. #{e.message}

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