Common Configuration Mistakes and Misunderstandings
====================================================

.. meta::
   :description: Common rsyslog configuration mistakes when moving from legacy syntax to modern RainerScript.
   :keywords: rsyslog, configuration mistakes, RainerScript, legacy syntax, action, stop, semicolon

.. summary-start

This section documents syntax patterns that are often misunderstood,
invalid, or misused in rsyslog configurations — especially when transitioning
from legacy syntax to modern RainerScript.

It is intended to help both human users and automated tools avoid common traps
when writing or validating rsyslog configuration files.

.. summary-end

.. list-table::
   :header-rows: 1
   :widths: 20 20 35 25

   * - Incorrect Syntax
     - Legacy Meaning
     - Why It's Invalid or Misleading
     - Correct Form (RainerScript)

   * - ``& stop``
     - Shorthand: same selector + stop message processing
     - Only valid in legacy syntax. ``&`` means "same selector". Not allowed in RainerScript.
     - Use:

       .. code-block:: rainerscript

          if <condition> then {
              action(...)
              stop
          }

   * - ``stop()``
     - Mistaken as a function call
     - Not a function; `stop` is a **bare statement** in RainerScript
     - Just use ``stop``

   * - ``& ~``
     - Discard message with same selector
     - Legacy shorthand only. ``~`` means discard. ``&`` invalid in RainerScript.
     - Use:

       .. code-block:: rainerscript

          if <condition> then {
              stop
          }

   * - ``action(type="stop")``
     - Assumes "stop" is an action module
     - There is no such module. ``stop`` is a statement, not an action.
     - Use bare ``stop`` as a control flow statement

   * - ``action(type="omfile" file="/var/log/example.log");``
     - Looks like C-style statement termination
     - Modern RainerScript objects are not terminated by semicolons. The
       trailing ``;`` is parsed as an invalid character.
     - Remove the semicolon:

       .. code-block:: rainerscript

          action(type="omfile" file="/var/log/example.log")

   * - ``if (...) then stop();``
     - Combines multiple errors: function call and syntax mismatch
     - Parentheses are invalid, and ``stop`` is not a function
     - Use ``if (...) then stop`` or wrap in a block as needed

.. note::

   These mistakes are common in AI-generated configs or user translations
   from legacy examples. Always validate your configuration with:

   .. code-block:: bash

      rsyslogd -N1
