fluent/fluentd · error · Fluent::ConfigError

ca_private_key_path is required when ca_cert_path is specifi

Error message

ca_private_key_path is required when ca_cert_path is specified

What it means

In cert_option_server_validate! (cert_option.rb:75-77), when <transport tls> is configured with ca_cert_path (use a CA to sign a server certificate on the fly), the CA's private key ca_private_key_path is mandatory: fluentd generates a fresh server certificate at startup and signs it with the CA key. Without ca_private_key_path the signing operation is impossible, so configuration fails immediately with this Fluent::ConfigError.

Source

Thrown at lib/fluent/plugin_helper/cert_option.rb:76

                                  sandbox.instance_eval(conf.cert_verifier)
                                end
        end

        Fluent::TLS.set_version_to_context(ctx, version, conf.min_version, conf.max_version)
        ctx.ciphers = ciphers unless insecure

        ctx
      end

      def cert_option_server_validate!(conf)
        case
        when conf.cert_path
          raise Fluent::ConfigError, "private_key_path is required when cert_path is specified" unless conf.private_key_path
          log.warn "For security reason, setting private_key_passphrase is recommended when cert_path is specified" unless conf.private_key_passphrase
          cert_option_load(conf.cert_path, conf.private_key_path, conf.private_key_passphrase)

        when conf.ca_cert_path
          raise Fluent::ConfigError, "ca_private_key_path is required when ca_cert_path is specified" unless conf.ca_private_key_path
          log.warn "For security reason, setting ca_private_key_passphrase is recommended when ca_cert_path is specified" unless conf.ca_private_key_passphrase
          generate_opts = cert_option_cert_generation_opts_from_conf(conf)
          cert_option_generate_server_pair_by_ca(
            conf.ca_cert_path,
            conf.ca_private_key_path,
            conf.ca_private_key_passphrase,
            generate_opts
          )

        when conf.insecure
          log.warn "insecure TLS communication server is configured (using 'insecure' mode)"
          generate_opts = cert_option_cert_generation_opts_from_conf(conf)
          cert_option_generate_server_pair_self_signed(generate_opts)

        else
          raise Fluent::ConfigError, "no valid cert options configured. specify either 'cert_path', 'ca_cert_path' or 'insecure'"
        end
      end

View on GitHub (pinned to dd45c6e18d)

Solutions

Add ca_private_key_path /etc/fluent/ca-key.pem alongside ca_cert_path in <transport tls>
Confirm the CA key is readable by the fluentd user and matches the CA cert (compare modulus via openssl rsa / openssl x509)
If the CA private key genuinely cannot live on this node, switch modes: use cert_path + private_key_path with a pre-issued server certificate instead of CA-signed generation
Set ca_private_key_passphrase too if the CA key is encrypted (fluentd also warns when it is absent)

Example fix

# before
<transport tls>
  ca_cert_path /etc/fluent/ca-cert.pem
</transport>
# => ca_private_key_path is required when ca_cert_path is specified

# after
<transport tls>
  ca_cert_path /etc/fluent/ca-cert.pem
  ca_private_key_path /etc/fluent/ca-key.pem
</transport>

Defensive patterns

Strategy: validation

Validate before calling

tls = { 'ca_cert_path' => '/etc/fluent/ca.pem', 'ca_private_key_path' => '/etc/fluent/ca.key' }
raise 'ca_private_key_path missing' if tls['ca_cert_path'] && !tls['ca_private_key_path']

Try / catch

begin
  agent.configure(conf)
rescue Fluent::ConfigError => e
  if e.message.include?('ca_private_key_path is required')
    abort 'supply the CA key, or switch to a pre-issued cert_path/private_key_path pair'
  end
  raise
end

Prevention

Document internally that ca_cert_path mode requires the CA's private key on the node — it signs server certs at startup
If policy forbids shipping CA keys, pre-issue server certs and use cert_path + private_key_path instead
Dry-run configs whenever TLS mode changes (CA-signed vs pre-issued vs insecure)

When it happens

Trigger: A <transport tls> block containing ca_cert_path /etc/fluent/ca.pem but no ca_private_key_path. Also happens when an operator confuses the two modes and supplies a server cert_path-less config mixing client-side ca_path terminology with the server-side ca_cert_path option.

Common situations: Setting up fluentd-to-fluentd forwarding where the output config declares a CA cert; operators supplying only the public CA certificate copied from the CA host; secret-management pipelines that provision CA certs but restrict CA keys, forgetting the forwarder needs the key to mint server certs.

Related errors

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