When building custom detections in Wazuh, one of the most frustrating problems is creating a decoder that appears correct but refuses to match logs during testing.
You run the event through Wazuh Logtest, expect your custom decoder to trigger, and instead see messages indicating that no decoder matched or that an unexpected decoder processed the event.
What the “Custom Decoder Isn’t Matching” Problem Means in Wazuh
The “Custom Decoder Isn’t Matching” issue occurs when Wazuh cannot associate an incoming log with the decoder you created.
Since decoders are responsible for parsing raw log data into structured fields, a failure at this stage prevents downstream rules from working correctly.
In most cases, the decoder exists and is loaded by Wazuh, but one or more matching conditions fail.
These conditions may include:
- Incorrect parent decoder relationships
- Regular expressions that do not match the log format
- Prematch patterns that fail validation
- Decoder ordering issues
- XML syntax errors
- Unexpected log transformations during processing
Because decoder matching occurs before rule evaluation, even a perfectly written detection rule becomes useless if the decoder never activates.
Why Decoder Matching Is Critical for Alert Generation
Wazuh follows a multi-stage event processing pipeline.
Before a rule can generate an alert, Wazuh must first understand the structure of the incoming log.
A decoder performs tasks such as:
- Identifying log types
- Extracting usernames, IP addresses, file paths, and other fields
- Categorizing events
- Passing structured data to rules
Without successful decoding:
- Fields cannot be extracted
- Rule conditions cannot be evaluated
- Alerts are never generated
- Dashboards display incomplete information
This dependency is why decoder troubleshooting should always be the first step when custom rules fail.
If you are new to custom detection development, see our guide: How to Create Custom Detection Rules in Wazuh (With Examples).
Common Symptoms Seen in Wazuh Logtest
Several warning signs typically indicate a decoder matching problem.
Common symptoms include:
- Logtest reports “No decoder matched”
- The event matches a generic decoder instead of the custom one
- Extracted fields appear empty
- Custom rules never trigger
- Parent decoders fail unexpectedly
- Regex captures return incorrect values
- Alert fields are missing in the dashboard
These symptoms often point to decoder configuration errors rather than rule issues.
What Readers Will Learn in This Guide
This guide provides a deep dive into diagnosing and resolving decoder matching failures in Wazuh Logtest.
You will learn:
- How Wazuh decoders function internally
- How Logtest processes events
- Why decoder matching fails
- How decoder hierarchy and precedence work
- Methods for validating regex patterns
- Techniques for debugging field extraction problems
- Best practices that prevent future decoder issues
By the end of this guide, you will have a systematic troubleshooting process that can be applied to virtually any custom decoder problem.
Understanding How Wazuh Decoders Work
Before troubleshooting decoder failures, it is important to understand exactly how decoders fit into the Wazuh event processing pipeline.
Many decoder problems stem from misunderstandings about when decoders execute, how parent-child relationships work, and how rules consume extracted fields.
What Is a Wazuh Decoder?
A Wazuh decoder is an XML-based parsing component that analyzes incoming logs and extracts structured information from them.
Its primary job is to convert unstructured text into named fields that rules can evaluate.
For example, a raw log such as:
Failed login from 192.168.1.50 user=admin
might be transformed into:
srcip: 192.168.1.50
user: admin
Once those fields exist, rules can perform meaningful security analysis.
Purpose of Decoders in the Wazuh Analysis Pipeline
Decoders serve as the bridge between raw log data and actionable detections.
Their responsibilities include:
- Identifying event formats
- Parsing message content
- Extracting field values
- Normalizing event data
- Preparing events for rule evaluation
Without decoders, Wazuh would only see plain text logs and would be unable to make intelligent detection decisions.
Relationship Between Decoders and Rules
Decoders and rules work together but serve different purposes.
Decoders answer:
“What information exists in this log?”
Rules answer:
“What should we do with that information?”
For example:
Decoder extracts:
user=root
srcip=10.10.10.15
action=failed
Rule evaluates:
If action=failed and user=root then generate alert.
If the decoder fails to extract those fields, the rule has nothing to evaluate.
For a deeper look at rule development, see:
How Raw Logs Become Structured Events
When Wazuh receives a log, it passes through several processing stages before an alert is created.
The decoder stage is where raw text becomes structured security data.
This transformation enables:
- Correlation
- Alerting
- Dashboard visualization
- Threat hunting
- Compliance reporting
The Wazuh Event Processing Flow
Understanding the complete event pipeline helps identify where failures occur.
Log Collection
Logs are collected from agents, syslog sources, APIs, integrations, or cloud services.
Examples include:
- Windows Event Logs
- Linux Syslog
- Firewall logs
- Application logs
- Cloud audit logs
Related guides:
How to Monitor Windows Event Logs Using Wazuh
How to Configure Wazuh as a Centralized Syslog Server
Pre-Decoding Stage
Wazuh first performs pre-decoding.
During this phase, it attempts to identify metadata such as:
- Timestamp
- Hostname
- Program name
- Process information
No custom field extraction occurs yet.
The official Wazuh decoder documentation explains this stage in greater detail.
Decoding Stage
Next, Wazuh evaluates available decoders.
The engine checks:
- Prematch conditions
- Parent decoder requirements
- Regular expression matches
- Decoder hierarchy
If a decoder successfully matches, field extraction occurs.
If not, processing continues until another decoder matches or no match is found.
Rule Matching Stage
Once decoding succeeds, extracted fields become available to rules.
Rules can evaluate:
- Source IP addresses
- Usernames
- File names
- URLs
- Process names
- Custom fields
Successful rule matches produce alert candidates.
Alert Generation
After rule evaluation, Wazuh creates alerts and forwards them to:
- The indexer
- Dashboard
- Email notifications
- Integrations
- Active response components
Any decoder failure earlier in the pipeline prevents this stage from occurring.
How Wazuh Logtest Evaluates Events
Wazuh Logtest is the most valuable troubleshooting tool available for decoder development.
It allows administrators to simulate event processing without waiting for production logs.
What Logtest Does
Logtest processes an event through the same analysis engine used by Wazuh Manager.
It displays:
- Pre-decoding results
- Decoder matches
- Extracted fields
- Rule matches
- Generated alerts
This visibility makes it much easier to identify where failures occur.
Differences Between Logtest and Production Log Processing
Although Logtest closely resembles production processing, there can be subtle differences.
Examples include:
- Log forwarding behavior
- Agent-side transformations
- Syslog formatting changes
- External integrations
- Encoding differences
A decoder that works in Logtest but fails in production often indicates that the actual incoming log differs from the test sample.
The official Wazuh Logtest documentation provides additional implementation details.
Why Logtest Is the Best Troubleshooting Tool
Security engineers frequently rely on Logtest because it provides immediate feedback.
Benefits include:
- Rapid testing cycles
- Visibility into each processing phase
- Verification of extracted fields
- Rule validation
- Decoder hierarchy debugging
Industry logging experts often emphasize that parser validation should occur before detection engineering because parsing failures are among the most common causes of missed alerts.
Guidance from the OWASP Logging Cheat Sheet similarly stresses the importance of consistent event normalization and validation before security monitoring occurs.
Common Symptoms of Decoder Matching Failures
Decoder matching failures can appear in several different ways.
Understanding the symptom often helps identify the root cause much faster.
Logtest Shows “No Decoder Matched”
This is the most obvious decoder failure.
Example Output
You may see output similar to:
**Phase 1: Completed pre-decoding.
full event: 'User login failed from 192.168.1.20'
**Phase 2: Completed decoding.
No decoder matched.
What It Indicates
This typically means:
- Prematch conditions failed
- Parent decoder requirements were not satisfied
- Regex patterns did not match
- Decoder files were not loaded
- Decoder ordering prevented evaluation
In most cases, the issue exists in the decoder definition itself rather than in the rule.
Logs Match a Generic Decoder Instead of Your Custom Decoder
Sometimes Logtest reports a decoder match, but not the decoder you intended.
For example:
decoder: syslog
instead of:
decoder: custom_application_decoder
Why Decoder Precedence Matters
Wazuh evaluates decoders according to internal matching logic and hierarchy.
A generic decoder may capture the event before your custom decoder has an opportunity to process it.
Common causes include:
- Broad prematch patterns
- Incorrect parent relationships
- Decoder ordering conflicts
- Overlapping regex definitions
Impact on Rule Execution
When the wrong decoder matches:
- Expected fields are not extracted
- Rules reference missing fields
- Alert conditions fail
- Dashboards display incomplete information
This often creates the false impression that the rule is broken when the actual issue is decoder selection.
Fields Are Missing Even Though the Decoder Appears to Match
A decoder match does not necessarily mean successful field extraction.
Partial Matches
A decoder may satisfy its matching conditions but fail to capture all intended fields.
Example:
decoder: custom_firewall
but:
srcip = NULL
user = NULL
This indicates extraction logic problems rather than matching problems.
Extraction Failures
Common causes include:
- Incorrect capture groups
- Regex syntax mistakes
- Unexpected log formats
- Escaping issues
- Field ordering mismatches
The decoder activates, but the extracted data never reaches the rule engine.
Rules Never Trigger After Decoder Creation
This symptom is extremely common.
Administrators often see:
decoder matched successfully
yet:
No rule matched.
Decoder Matched but Fields Not Extracted Correctly
A rule may depend on fields such as:
srcip
username
action
If those values are empty, malformed, or assigned to the wrong field names, rule conditions fail.
The decoder appears functional while detections remain broken.
Rule Dependency Issues
Even when field extraction works correctly, rules may still fail because:
- Rule IDs are incorrect
- Parent rules are missing
- Dependencies are not met
- Field names referenced by rules do not exist
- Rule conditions are overly restrictive
When troubleshooting, always validate the decoder first and the rule second.
If your custom rule still does not fire after decoder validation, see:
How to Create Custom Detection Rules in Wazuh (With Examples)
and
How to Reproduce the Problem Using Wazuh Logtest
Before attempting to fix a decoder, you should first reproduce the failure in a controlled environment.
Wazuh Logtest provides a safe way to isolate decoder issues without waiting for logs to arrive through production pipelines.
Reproducing the problem consistently is often the fastest path to identifying the root cause.
Launching Wazuh Logtest
Wazuh Logtest can be accessed either from the command line or through the Wazuh Dashboard.
Both methods use the same analysis engine, making them equally useful for troubleshooting.
Using the Command Line
The command-line version is preferred by many administrators because it provides direct access to the analysis engine.
On the Wazuh Manager server, launch Logtest using:
/var/ossec/bin/wazuh-logtest
After launching, paste a sample log and press Enter.
Example:
Jul 10 15:20:11 firewall sshd[1234]: Failed password for admin from 192.168.1.100
Logtest immediately displays:
- Pre-decoding results
- Decoder matches
- Extracted fields
- Rule matches
This allows rapid iteration while developing custom decoders.
Using the Wazuh Dashboard
The Wazuh Dashboard provides a graphical interface for Logtest.
Navigate to:
Wazuh Dashboard → Tools → Ruleset Test
Paste a log event into the testing window and run the analysis.
The dashboard view is especially useful when:
- Demonstrating decoder behavior to team members
- Troubleshooting remotely
- Reviewing field extraction visually
If you are experiencing dashboard-related issues, see:
Wazuh Dashboard Not Loading? Complete Troubleshooting Guide
Capturing Sample Logs for Testing
The quality of your test data directly affects troubleshooting accuracy.
Many decoder issues occur because administrators test against logs that differ from actual production events.
Using Actual Production Logs
Whenever possible, copy logs directly from:
/var/ossec/logs/archives/archives.log- Syslog files
- Application logs
- Windows Event Logs
- Network device logs
Using authentic production data ensures your decoder is tested against the exact format Wazuh receives.
Avoiding Altered Test Data
A common mistake is manually rewriting logs for readability.
For example:
Original log:
2026-06-01T12:45:11Z app01 auth-service[344]: Login failed user=admin ip=10.1.5.12
Modified test log:
Login failed user=admin ip=10.1.5.12
The modified version may fail because:
- Timestamp structure changed
- Program name removed
- Pre-decoding metadata altered
Always test using the raw event whenever possible.
Reading Logtest Output Correctly
Many administrators focus only on whether a decoder matched and overlook the diagnostic information contained in each processing phase.
Understanding Logtest’s output structure is critical for troubleshooting.
Phase 1: Pre-decoding
Phase 1 extracts metadata from the event.
Example:
**Phase 1: Completed pre-decoding.
full event: 'Jul 10 15:20:11 firewall sshd[1234]: Failed password'
timestamp: 'Jul 10 15:20:11'
hostname: 'firewall'
program_name: 'sshd'
This stage helps verify:
- Timestamp recognition
- Hostname extraction
- Program identification
If expected values are missing here, later decoder stages may fail.
Phase 2: Decoding
This phase determines whether a decoder matched the log.
Example:
**Phase 2: Completed decoding.
name: 'custom_sshd_decoder'
srcip: '192.168.1.100'
user: 'admin'
Or:
**Phase 2: Completed decoding.
No decoder matched.
Most custom decoder problems become visible in Phase 2.
Phase 3: Rule Matching
Once decoding succeeds, Wazuh evaluates rules.
Example:
**Phase 3: Completed filtering (rules).
id: '100200'
level: '10'
description: 'Failed SSH login detected'
If decoding succeeds but no rules trigger, the issue typically resides in the rule logic rather than the decoder.
Root Cause #1: Incorrect Regular Expressions
Among all decoder failures, incorrect regular expressions are the most common cause.
A single misplaced character can prevent Wazuh from matching logs or extracting fields correctly.
Understanding Regex Behavior in Wazuh Decoders
Wazuh relies heavily on regular expressions for parsing log content.
These expressions determine:
- Whether a decoder matches
- Which fields are extracted
- How data is normalized
Because decoder matching depends on regex evaluation, even minor syntax errors can cause complete decoder failure.
OSRegex vs PCRE2
Wazuh supports multiple regex engines.
OSRegex
OSRegex is Wazuh’s traditional regex engine.
Advantages:
- Fast execution
- Lower resource consumption
- Suitable for most decoder scenarios
Limitations include fewer advanced pattern features.
PCRE2
PCRE2 provides more advanced capabilities.
Examples include:
- Lookaheads
- Lookbehinds
- Complex grouping
- Advanced quantifiers
The official PCRE2 documentation provides a detailed overview of supported syntax.
When troubleshooting, verify that your decoder uses syntax supported by the configured regex engine.
Common Regex Limitations
Even experienced engineers sometimes assume all regex engines behave identically.
Common limitations include:
- Unsupported lookbehinds
- Different escape requirements
- Grouping behavior differences
- Engine-specific quantifiers
A regex that works in an online tester may fail inside Wazuh if the engine differs.
Common Regex Mistakes
Several mistakes appear repeatedly in decoder troubleshooting cases.
Missing Escape Characters
Characters such as:
.
[
]
(
)
+
*
?
have special regex meanings.
For example:
Incorrect:
10.1.1.1
Correct:
10\.1\.1\.1
Without escaping, the regex may match unintended content.
Greedy Matching Problems
Greedy quantifiers frequently consume more data than intended.
Example:
user=(.*)
This may capture everything until the end of the log.
A more precise alternative might be:
user=([^\s]+)
This captures only the username.
Incorrect Character Classes
Character classes are often too restrictive or too broad.
Example:
([A-Za-z]+)
This fails if usernames contain:
admin-01
svc_account
user123
A more realistic pattern might be:
([A-Za-z0-9_-]+)
Anchoring Errors
Anchors determine where matching begins and ends.
Example:
^Failed login
This only matches logs beginning with “Failed login”.
If the event starts with a timestamp, the decoder never matches.
Anchoring mistakes are especially common when testing simplified logs instead of production events.
Testing Regex Independently Before Deployment
Always validate regex patterns before adding them to production decoders.
This significantly reduces troubleshooting time.
Regex Testing Tools
Useful validation resources include:
- Regex101
- PCRE2 test environments
- Local command-line regex tools
Regex101 is widely used by security engineers because it explains matching behavior and capture groups visually.
Validation Techniques
Before deploying a decoder:
- Test against multiple real logs.
- Validate all capture groups.
- Verify edge cases.
- Test malformed input.
- Confirm field ordering.
Many detection engineering teams recommend maintaining a library of representative sample logs to validate parser behavior after every decoder modification.
Root Cause #2: Prematch Conditions Never Match
Another extremely common reason for decoder failure is a prematch condition that never evaluates to true.
In these cases, Wazuh never reaches the regex extraction stage because the decoder is filtered out beforehand.
What the Prematch Directive Does
The <prematch> directive acts as a preliminary filter.
Instead of running expensive regex operations against every incoming event, Wazuh first checks whether the log contains a specific identifying pattern.
Example:
<prematch>Failed login</prematch>
Only logs containing “Failed login” proceed to the decoder’s regex stage.
Performance Benefits
Prematch conditions improve performance by:
- Reducing regex evaluations
- Accelerating event processing
- Lowering CPU consumption
- Improving scalability
This filtering mechanism becomes especially valuable in high-volume environments.
For performance optimization strategies, see:
Why Is Wazuh Using High CPU? Troubleshooting Guide
Decoder Filtering Behavior
A decoder with a failed prematch is effectively invisible.
Example:
<prematch>Authentication failed</prematch>
Incoming log:
Login failure detected
Because the strings differ, the decoder never executes.
Common Prematch Errors
Most prematch failures originate from assumptions about log content.
Case Sensitivity Issues
Prematch checks are often case-sensitive.
Example:
Decoder:
<prematch>Failed Login</prematch>
Log:
failed login
The mismatch prevents decoder execution.
Typographical Errors
Simple spelling mistakes frequently go unnoticed.
Examples:
Authentcation Failed
instead of:
Authentication Failed
Even one missing character causes complete failure.
Extra Spaces and Hidden Characters
Logs may contain:
- Tabs
- Multiple spaces
- Non-printable characters
- Unicode whitespace
These characters can prevent expected matches.
Administrators often discover this issue when copying logs from dashboards or email systems.
Incorrect Log Format Assumptions
Many custom decoders are built using documentation examples rather than real events.
For example, documentation may show:
Login failed for user admin
while production logs contain:
Authentication failure username=admin
The prematch succeeds only if it reflects actual log content.
Troubleshooting Prematch Failures
To diagnose prematch issues:
- Remove the prematch temporarily.
- Test the decoder again.
- Confirm the decoder begins matching.
- Reintroduce a simpler prematch.
- Gradually refine the condition.
This process quickly isolates whether the failure occurs during filtering or extraction.
Root Cause #3: Parent Decoder Dependencies
Many advanced decoder configurations use parent-child relationships.
When parent decoders fail, every dependent child decoder also fails.
Understanding Parent and Child Decoders
Parent-child hierarchies allow multiple decoders to process related log formats efficiently.
Example:
Parent decoder:
<decoder name="my_application">
Child decoder:
<decoder name="my_application_login">
<parent>my_application</parent>
</decoder>
The child decoder can only execute after the parent decoder matches successfully.
Decoder Hierarchy Explained
Hierarchy reduces duplication by allowing:
- Shared prematch conditions
- Common parsing logic
- Modular decoder design
- Easier maintenance
This approach is common in large enterprise rulesets.
Matching Sequence
The decoder evaluation process generally follows this order:
- Parent decoder evaluated.
- Parent decoder matches.
- Child decoder becomes eligible.
- Child decoder evaluates additional conditions.
- Field extraction occurs.
If step 2 fails, the remaining steps never occur.
Why Child Decoders Fail
Child decoders frequently appear broken when the actual problem resides higher in the hierarchy.
Parent Decoder Never Matches
This is the most common cause.
Example:
<parent>apache_access</parent>
If the parent decoder fails due to regex or prematch issues, every dependent decoder fails automatically.
Always validate the parent decoder first.
Incorrect Parent Name References
A simple naming mismatch can break the entire chain.
Example:
Parent:
<decoder name="apache_access">
Child:
<parent>apache-access</parent>
Because the names differ, Wazuh cannot establish the relationship.
Nested Decoder Configuration Errors
Complex decoder trees sometimes contain:
- Circular references
- Missing parents
- Incorrect nesting
- Conflicting decoder names
These configuration errors can be difficult to identify without systematic testing.
The official Wazuh decoder documentation contains examples of proper parent-child decoder implementations.
Validating Decoder Chains
When troubleshooting decoder hierarchies:
- Test the parent decoder alone.
- Confirm parent matching succeeds.
- Verify extracted fields.
- Enable the child decoder.
- Validate each layer independently.
- Add complexity gradually.
Many experienced detection engineers recommend building decoder chains incrementally rather than creating entire hierarchies at once.
This approach makes failures easier to isolate and significantly reduces debugging time.
Root Cause #4: Decoder File Loading Problems
Sometimes a decoder is perfectly written but never executes because Wazuh never loads it into memory.
When this occurs, Logtest behaves as if the decoder does not exist, regardless of how accurate the regex or prematch conditions may be.
For this reason, decoder loading verification should always be part of your troubleshooting process.
Where Custom Decoders Are Stored
Wazuh stores decoder definitions in XML files that are loaded by the analysis engine during startup.
Decoder File Locations
In most deployments, custom decoders are placed in:
/var/ossec/etc/decoders/
Some environments may also use:
/var/ossec/ruleset/decoders/
However, modifying the vendor-supplied ruleset directly is generally discouraged because upgrades can overwrite changes.
The official Wazuh documentation recommends storing custom content separately from the default ruleset whenever possible.
Best Practices for Organization
As custom content grows, maintaining a clear structure becomes increasingly important.
Recommended practices include:
- Group related decoders into dedicated files
- Use descriptive filenames
- Separate vendor and custom content
- Document decoder purposes
- Maintain version control
Example:
custom-firewall_decoders.xml
custom-vpn_decoders.xml
custom-webapp_decoders.xml
This approach simplifies troubleshooting and future maintenance.
How Wazuh Loads Decoder Files
Understanding the loading process helps explain why certain decoders fail to appear during testing.
Startup Loading Process
When the Wazuh Manager starts:
- Decoder XML files are discovered.
- XML syntax is validated.
- Decoder definitions are parsed.
- Internal decoder trees are built.
- Decoders become available for event processing.
Any failure during these stages can prevent decoder loading.
Load Order Considerations
Decoder loading order can affect matching behavior.
Factors include:
- Filename ordering
- Parent-child dependencies
- Decoder hierarchy construction
- Rule engine initialization
Although Wazuh evaluates decoder logic rather than simply using the first file loaded, load order can still influence how overlapping decoder definitions behave.
This becomes especially important in environments containing many custom decoders.
Detecting Decoder Syntax Errors
A single XML syntax error can prevent an entire decoder file from loading.
Unfortunately, administrators often focus on regex troubleshooting while overlooking XML validation problems.
XML Formatting Problems
Common formatting mistakes include:
<decoder name="custom_decoder"
instead of:
<decoder name="custom_decoder">
Even small formatting errors can invalidate the decoder definition.
Missing Tags
Missing opening or closing tags frequently cause loading failures.
Example:
Incorrect:
<decoder name="vpn_decoder">
<prematch>VPN Login
</decoder>
Correct:
<decoder name="vpn_decoder">
<prematch>VPN Login</prematch>
</decoder>
XML parsers require complete tag structures.
Invalid Attributes
Attributes must follow supported Wazuh syntax.
Examples of problematic configurations include:
<decoder name="">
or
<decoder invalidattribute="true">
Unsupported attributes may cause parser failures or unexpected behavior.
Verifying Decoder Loading in Logs
The fastest way to confirm decoder loading is by reviewing manager logs.
Common locations include:
/var/ossec/logs/ossec.log
Look for messages related to:
- XML parsing
- Decoder loading
- Ruleset initialization
- Startup failures
Examples include:
ERROR: Invalid decoder configuration.
or:
ERROR: XML syntax error found.
Whenever a decoder fails unexpectedly, checking the manager logs should be one of the first troubleshooting steps.
If you are already troubleshooting manager stability issues, see:
Troubleshooting Wazuh Manager Core Dumps
Root Cause #5: Decoder Order and Precedence Issues
A decoder may be valid, loaded successfully, and contain correct regex patterns, yet still never match because another decoder processes the event first.
This is known as a decoder precedence issue.
How Wazuh Chooses Between Multiple Matching Decoders
Multiple decoders can often match the same log.
When this happens, Wazuh must determine which decoder ultimately processes the event.
Understanding this selection process is critical when building custom parsers.
Matching Priority Behavior
Wazuh evaluates decoders using several factors:
- Parent-child relationships
- Prematch conditions
- Decoder specificity
- Decoder hierarchy
- Internal matching logic
A more generic decoder can sometimes capture events before a custom decoder has an opportunity to extract fields.
Decoder Evaluation Sequence
A simplified workflow looks like:
- Pre-decoding occurs.
- Candidate decoders are identified.
- Parent decoders are evaluated.
- Matching logic is applied.
- A decoder is selected.
- Fields are extracted.
The existence of a matching decoder does not guarantee that your custom decoder will be selected.
Generic Decoders Overriding Custom Decoders
This is one of the most common causes of unexpected Logtest results.
Why This Happens
Many built-in Wazuh decoders are intentionally broad.
For example:
- Syslog decoders
- Generic application decoders
- Network service decoders
A custom decoder with a weak prematch condition may lose to one of these broader parsers.
Examples
Suppose a custom decoder is designed for:
Failed login for user admin
but a generic syslog decoder already recognizes the event structure.
Logtest may show:
decoder: syslog
instead of:
decoder: custom_auth_decoder
As a result:
- Expected fields are missing
- Custom rules fail
- Alerts are never generated
Administrators often mistake this for a regex problem when the real issue is decoder selection.
Adjusting Decoder Placement
When precedence issues occur, consider:
- Making prematch conditions more specific
- Improving parent-child relationships
- Narrowing regex scope
- Reducing overlap with built-in decoders
Avoid relying on broad matching patterns whenever possible.
Best Practices for Ordering Decoders
To reduce precedence conflicts:
- Create highly specific prematch conditions
- Use parent decoders appropriately
- Avoid generic regex patterns
- Test against multiple log samples
- Validate matches using Logtest after every change
Many experienced Wazuh administrators build decoders from the most specific matching criteria outward rather than attempting to filter broad matches later.
Root Cause #6: Incorrect Program Name Matching
Program name mismatches frequently cause decoder failures, particularly when working with syslog-based data sources.
Administrators often assume the program name contains one value when Wazuh actually extracts something entirely different.
Understanding Program Name Extraction
The program name is typically identified during the pre-decoding phase and can be used by decoders as a filtering mechanism.
Syslog-Based Logs
Consider a syslog event:
Jul 15 12:30:11 firewall sshd[2345]: Failed password for admin
Logtest may display:
program_name: sshd
A decoder referencing a different program name will never match.
Application-Generated Logs
Application logs can behave differently.
For example:
2026-06-15T12:30:11 app-server auth-service: Login failed
The extracted program name might be:
auth-service
or another value depending on how the log is formatted and forwarded.
Never assume the program name without verifying it through Logtest.
Common Program Name Matching Errors
Several recurring mistakes appear in custom decoder implementations.
Incorrect Values
Example:
Decoder:
<program_name>apache</program_name>
Actual value:
apache2
Because the values differ, matching fails.
Case Mismatches
Case sensitivity can also cause problems.
Example:
Decoder:
<program_name>SSHD</program_name>
Logtest output:
program_name: sshd
Even minor case differences can prevent matching.
Unexpected Log Sources
Logs frequently pass through:
- Syslog relays
- Load balancers
- Forwarders
- SIEM integrations
During transit, metadata may change.
For example, a device log originally generated by:
vpn-service
may arrive as:
rsyslog
depending on the forwarding path.
Verifying Program Name Values in Logtest
Always verify program names directly from Phase 1 output.
Example:
**Phase 1: Completed pre-decoding.
program_name: 'sshd'
This value should be copied exactly into decoder definitions whenever program-name filtering is used.
If logs are being centralized through syslog infrastructure, see:
How to Configure Wazuh as a Centralized Syslog Server
Root Cause #7: XML Configuration Errors
Even when decoder logic is correct, XML configuration problems can prevent Wazuh from loading or interpreting the decoder properly.
These issues are particularly common when manually editing decoder files.
Common Decoder XML Mistakes
XML-related problems often produce misleading symptoms.
A decoder may:
- Fail to load entirely
- Partially load
- Ignore specific elements
- Break dependent decoders
Careful XML validation is therefore essential.
Unclosed Tags
One of the most common mistakes is leaving tags incomplete.
Incorrect:
<regex>user=(\S+)
Correct:
<regex>user=(\S+)</regex>
XML parsers require proper opening and closing tags.
Invalid Decoder Structures
Decoder elements must appear in supported structures.
Example of problematic nesting:
<decoder name="custom">
<regex>
<prematch>Login</prematch>
</regex>
</decoder>
The decoder may fail because the elements are not organized correctly.
Always follow the structures documented by Wazuh.
Duplicate Decoder Names
Each decoder should have a unique name.
Problematic example:
<decoder name="custom_auth">
appearing multiple times across different files.
Duplicate names can create confusion during troubleshooting and may lead to unexpected matching behavior.
Use descriptive and unique identifiers.
Unsupported Elements
Occasionally administrators copy examples from unrelated XML formats.
Examples of unsupported elements may include:
<condition>
<priority>
<action>
if those elements are not recognized within decoder definitions.
Unsupported tags may cause parser errors or be ignored entirely.
Validating Decoder Files Before Restarting Wazuh
Before restarting the manager:
- Review XML formatting carefully.
- Verify opening and closing tags.
- Confirm decoder names are unique.
- Check parent references.
- Test XML syntax using validation tools.
- Review startup logs after restart.
Many organizations include XML validation in their change-management process because syntax errors remain one of the leading causes of decoder deployment failures.
For additional guidance on configuration validation and troubleshooting, consult the official Wazuh decoder documentation:
Root Cause #8: Special Characters and Log Formatting Issues
Sometimes a decoder appears completely correct, yet matching still fails.
In many of these cases, the problem is not the decoder itself but hidden formatting differences inside the log data.
These issues are particularly common when logs are collected from multiple operating systems, applications, cloud services, or forwarding platforms.
Hidden Characters That Break Matching
Many characters are invisible when viewing logs in terminals, dashboards, or text editors.
A log may appear identical to the expected format while containing hidden characters that prevent decoder matching.
Common examples include:
- Tabs
- Carriage returns
- Line feeds
- Unicode whitespace
- Non-printable control characters
Because regular expressions evaluate the actual underlying data, these invisible characters can cause unexpected failures.
Tabs
Tabs often appear when logs originate from:
- Network devices
- CSV exports
- Legacy applications
- Custom scripts
Example:
Expected log:
user=admin ip=10.10.10.5
Actual log:
user=admin\tip=10.10.10.5
A regex expecting a standard space may fail completely.
When troubleshooting, inspect raw logs carefully rather than relying on visual formatting.
Carriage Returns
Windows-based systems frequently use carriage return and line feed sequences.
For example:
\r\n
These characters may interfere with:
- Prematch evaluation
- Regex extraction
- Multi-line parsing
This issue commonly appears when logs are transferred between Windows and Linux systems.
Unicode Characters
Unicode-related problems are becoming more common as organizations collect logs globally.
Examples include:
- Smart quotation marks
- Non-breaking spaces
- Unicode dashes
- International character sets
A decoder expecting:
-
may not match:
–
even though they appear visually similar.
Multi-Line Log Challenges
Many applications generate events spanning multiple lines.
Traditional decoder designs often assume each event exists on a single line.
When this assumption is incorrect, matching failures become likely.
Stack Traces
Java, .NET, Python, and other application platforms commonly generate stack traces.
Example:
Exception occurred
at Service.Login()
at Service.Validate()
at Application.Main()
A decoder built for only the first line may fail to capture critical information.
Application Exceptions
Application exceptions often include:
- Nested error messages
- Variable-length content
- Dynamic identifiers
- Embedded JSON
These structures can complicate parsing significantly.
JSON and Structured Log Parsing Issues
Modern applications increasingly produce structured logs.
Example:
{
"event":"login_failure",
"user":"admin",
"ip":"10.10.10.5"
}
Challenges include:
- Escaped characters
- Nested objects
- Arrays
- Field ordering differences
The official JSON documentation from the standards community highlights how structured data can vary significantly across implementations.
When working with JSON logs, validate the exact structure received by Wazuh rather than assuming it matches application documentation.
Advanced Troubleshooting Techniques
If basic troubleshooting fails to identify the problem, deeper diagnostic methods can reveal exactly where decoder processing breaks down.
These techniques are particularly useful for complex environments containing large custom rulesets.
Increasing Wazuh Analysis Debug Logging
Debug logging provides visibility into how the analysis engine evaluates events.
This information can be invaluable when decoder matching behaves unexpectedly.
Enabling Debug Mode
Debug logging can be enabled for analysis components through Wazuh configuration settings.
Depending on your version and deployment architecture, this may involve modifying manager configuration files and restarting services.
Always enable debug logging in a controlled manner because verbose output can increase disk usage and processing overhead.
The official Wazuh troubleshooting documentation provides version-specific guidance.
Reviewing analysisd Logs
The Analysis Daemon (analysisd) is responsible for:
- Decoder processing
- Rule evaluation
- Alert generation
Reviewing its logs can reveal:
- Matching failures
- Parsing errors
- Decoder loading problems
- Ruleset issues
These logs often contain information not visible through Logtest alone.
Monitoring Decoder Loading During Startup
Startup logs provide critical information about decoder initialization.
If a decoder never loads successfully, runtime troubleshooting becomes impossible.
Relevant Log Files
Common locations include:
/var/ossec/logs/ossec.log
and other manager-related log files depending on deployment architecture.
These logs should always be reviewed after adding or modifying custom decoders.
What to Look For
Key warning signs include:
- XML parsing errors
- Decoder loading failures
- Parent decoder warnings
- Duplicate definitions
- Ruleset initialization problems
Examples:
Invalid decoder configuration
XML syntax error detected
Even a single warning can explain why a decoder never appears in Logtest.
Comparing Raw Logs with Decoder Expectations
One of the most effective troubleshooting techniques is performing a direct comparison between actual logs and decoder assumptions.
Side-by-Side Validation Process
Create a comparison table:
| Raw Log Component | Decoder Expectation |
|---|---|
| Program name | Program name filter |
| Timestamp | Regex assumptions |
| Username format | Capture group |
| IP address format | Extraction regex |
| Event text | Prematch condition |
Review each element individually.
This process frequently reveals subtle mismatches that are otherwise overlooked.
Isolating Decoder Components for Testing
Complex decoders can be difficult to debug because multiple conditions execute simultaneously.
Instead of troubleshooting the entire decoder at once, isolate individual components.
For example:
- Test only the prematch.
- Add a simple regex.
- Validate one field extraction.
- Add additional fields incrementally.
This approach narrows the failure point quickly.
Incremental Troubleshooting Strategy
Many experienced detection engineers follow a progressive workflow:
- Validate raw log format.
- Confirm pre-decoding output.
- Verify prematch behavior.
- Test regex extraction.
- Validate field mappings.
- Confirm rule execution.
- Verify alert generation.
This systematic approach prevents guesswork and reduces troubleshooting time significantly.
Building a Reliable Custom Decoder
The easiest decoder problems to solve are the ones that never occur.
Following a disciplined development process greatly improves decoder reliability and reduces future maintenance.
Step 1: Start With Prematch Validation
Begin with the simplest possible prematch condition.
Example:
<prematch>Login failed</prematch>
Run Logtest and confirm matching occurs before adding additional complexity.
This establishes a known-good foundation.
Step 2: Create a Minimal Decoder
Initially, focus only on achieving a successful decoder match.
Example:
<decoder name="custom_auth">
<prematch>Login failed</prematch>
</decoder>
Do not attempt field extraction immediately.
Confirm the decoder activates first.
Step 3: Add Field Extraction Gradually
Once matching succeeds, begin extracting fields one at a time.
Example:
<regex>user=(\S+)</regex>
<order>user</order>
Validate each new field before adding the next one.
This approach makes failures much easier to identify.
Step 4: Test Every Change with Logtest
After every modification:
- Run Logtest
- Verify decoder matching
- Confirm extracted fields
- Review rule execution
Frequent testing prevents small mistakes from accumulating into complex failures.
Step 5: Create Matching Rules
After decoding works correctly, create detection rules that use the extracted fields.
Step 6: Validate End-to-End Alert Generation
The final step is verifying the complete workflow:
Raw Log
→ Decoder Match
→ Field Extraction
→ Rule Match
→ Alert Generation
→ Dashboard Visibility
Successful Logtest results alone do not guarantee successful production alerts.
Always verify the entire pipeline.
Real-World Example: Fixing a Non-Matching Custom Decoder
Let’s walk through a realistic troubleshooting scenario to demonstrate how these concepts work in practice.
Original Log Sample
Suppose the application generates the following event:
AUTH FAILURE user=admin src=192.168.1.55
The goal is to create a decoder and rule that generate an alert whenever an authentication failure occurs.
Initial Decoder Configuration
Initial decoder:
<decoder name="custom_auth_failure">
<prematch>Authentication Failure</prematch>
<regex>user=(\S+) src=(\S+)</regex>
<order>user,srcip</order>
</decoder>
The administrator runs Logtest and receives:
No decoder matched.
Why the Decoder Failed
Several issues are present.
First, the prematch expects:
Authentication Failure
but the actual log contains:
AUTH FAILURE
Because the prematch never matches, Wazuh never evaluates the regex.
This is a classic decoder filtering failure.
Applying the Fix
The troubleshooting process begins by comparing the actual log with the decoder configuration.
Prematch Correction
Updated prematch:
<prematch>AUTH FAILURE</prematch>
Running Logtest again now produces:
decoder: custom_auth_failure
The decoder finally activates.
Regex Correction
Next, field extraction is validated.
Original regex:
user=(\S+) src=(\S+)
Suppose later logs occasionally contain additional trailing content:
AUTH FAILURE user=admin src=192.168.1.55 location=VPN
The regex is adjusted and tested against multiple samples to ensure consistent extraction.
Field Mapping Improvements
Logtest confirms:
user: admin
srcip: 192.168.1.55
Field names are verified against the planned rule conditions.
This ensures downstream rules can reference the extracted values correctly.
Successful Logtest Output
After correction:
**Phase 2: Completed decoding.
name: 'custom_auth_failure'
user: 'admin'
srcip: '192.168.1.55'
The decoder now performs as expected.
Rule Validation Results
The corresponding rule is tested:
**Phase 3: Completed filtering.
Rule id: 100500
Level: 10
Description: Authentication failure detected
The complete workflow succeeds:
Log Received
→ Decoder Matched
→ Fields Extracted
→ Rule Triggered
→ Alert Generated
This example illustrates a common reality of Wazuh troubleshooting: the decoder itself was not fundamentally broken.
A single prematch mismatch prevented the entire parsing pipeline from executing.
By validating each stage independently, the root cause was identified and resolved quickly.
Best Practices for Custom Decoder Development
Building a custom decoder that works today is only part of the challenge.
The real goal is creating decoders that remain reliable as log formats evolve, infrastructure changes, and Wazuh versions are upgraded.
Following a few proven development practices can dramatically reduce troubleshooting time and improve long-term maintainability.
Use Production Log Samples
One of the biggest mistakes administrators make is developing decoders using simplified or manually recreated logs.
Production logs often contain:
- Additional metadata
- Hidden characters
- Unexpected spacing
- Variable field ordering
- Application-specific formatting
Always collect samples directly from:
- Agent log files
- Syslog archives
- Application logs
- Wazuh archives
Testing against real-world data significantly increases decoder reliability.
Keep Regular Expressions Simple
Complex regular expressions are difficult to maintain and troubleshoot.
Whenever possible:
- Use explicit matching patterns
- Avoid excessive nesting
- Minimize optional groups
- Eliminate unnecessary wildcards
For example:
Instead of:
(.*)user=(.*)(.*)ip=(.*)
Use:
user=([^\s]+).*ip=([^\s]+)
Simpler patterns are easier to understand, validate, and modify.
Security engineering teams frequently emphasize parser simplicity because complex regex patterns are among the most common sources of maintenance issues and performance degradation.
Leverage Parent Decoders Carefully
Parent-child relationships can reduce duplication, but they also introduce dependencies.
Best practices include:
- Keep parent decoders stable
- Avoid deep decoder hierarchies
- Validate parent matches independently
- Document decoder relationships
Overly complex hierarchies can make troubleshooting significantly harder.
Document Decoder Logic
Every custom decoder should include documentation explaining:
- Its purpose
- Expected log format
- Field mappings
- Parent dependencies
- Associated rules
Documentation helps future administrators understand why a decoder exists and how it functions.
A simple comment block can save hours of troubleshooting later.
Test Changes in Staging First
Avoid deploying untested decoder modifications directly into production.
A staging environment allows you to:
- Validate matching behavior
- Confirm field extraction
- Test rule execution
- Verify dashboard visibility
This reduces the risk of detection gaps caused by configuration mistakes.
Maintain Version Control for Decoder Files
Custom decoders should be stored in version control systems such as Git.
Benefits include:
- Change tracking
- Rollback capability
- Peer review workflows
- Documentation history
- Easier collaboration
Version control is considered a best practice for all security monitoring content, including decoders and rules.
Retest After Wazuh Upgrades
Even if a decoder worked perfectly before an upgrade, it should be retested afterward.
Potential upgrade-related changes include:
- Parser behavior updates
- Ruleset modifications
- Decoder precedence changes
- Regex engine enhancements
- Configuration validation improvements
After upgrading, always review:
- Logtest results
- Manager logs
- Dashboard alerts
- Custom rule execution
If you’re planning a platform upgrade, see:
and
How to Build a Wazuh Indexer Cluster
Monitoring and Validation After the Fix
Successfully fixing a decoder is only the beginning.
You should also verify that the fix works consistently in production.
Continuous validation helps ensure that future log format changes do not silently break your detections.
Verify Decoder Matches in Logtest
Start by confirming that Logtest consistently reports the expected decoder.
Example:
name: 'custom_auth_decoder'
Test:
- Multiple log samples
- Expected events
- Edge cases
- Invalid events
A decoder should behave predictably across all supported log variations.
Confirm Field Extraction Accuracy
A decoder match alone is not enough.
Verify that every field contains the expected value.
Example:
user: admin
srcip: 10.10.10.5
action: failed
Watch for:
- Empty fields
- Truncated values
- Incorrect mappings
- Swapped capture groups
Field validation should be performed after every decoder modification.
Validate Rule Execution
Once decoding succeeds, verify that dependent rules trigger correctly.
Check:
- Rule IDs
- Alert levels
- Descriptions
- Field conditions
- Parent-child rule relationships
Monitor Live Events in Wazuh Dashboard
After deployment, review live events in the dashboard.
Confirm that:
- Alerts appear as expected
- Fields populate correctly
- Searches return expected results
- Visualizations display accurate data
The dashboard provides an important final validation layer.
Check Analysis Logs for Decoder Errors
Continue monitoring manager logs after deployment.
Look for:
- Decoder warnings
- Parsing failures
- XML validation errors
- Rule execution problems
Many organizations include log reviews as part of their post-deployment verification process.
Implement Ongoing Regression Testing
Production environments change constantly.
Applications may:
- Introduce new log formats
- Change field ordering
- Add metadata
- Modify message content
Regression testing helps identify these changes before they impact detection coverage.
A practical approach is maintaining a library of representative log samples and periodically validating them through Logtest after:
- Wazuh upgrades
- Application updates
- Infrastructure changes
- Decoder modifications
This practice significantly reduces the risk of silent detection failures.
Frequently Asked Questions (FAQ)
Question: Why does Wazuh Logtest show “No decoder matched”?
This message means that none of the available decoders successfully matched the event.
Common causes include:
- Incorrect regex patterns
- Failed prematch conditions
- Program name mismatches
- Parent decoder failures
- XML configuration errors
- Decoder loading problems
Review Phase 2 output in Logtest and validate each decoder condition individually.
Question: How do I determine whether prematch or regex is causing the failure?
Temporarily simplify the decoder.
First test only the prematch condition.
If the decoder begins matching, the issue likely resides in the regex.
If matching still fails, investigate:
- Prematch logic
- Program name filters
- Parent decoder requirements
This isolation strategy quickly narrows the problem area.
Question: Can multiple decoders match the same log?
Multiple decoders may be capable of matching a log, but Wazuh ultimately selects the decoder that satisfies its evaluation logic and hierarchy.
This is why decoder precedence and specificity are important when designing custom parsers.
Question: Why is my child decoder not being executed?
The most common reason is that the parent decoder never matched.
Other possible causes include:
- Incorrect parent names
- XML syntax issues
- Decoder hierarchy problems
- Configuration loading failures
Always validate the parent decoder first.
Question: How do I test a custom decoder without affecting production?
Use:
- Wazuh Logtest
- A staging environment
- Sample production logs
These methods allow you to validate matching behavior without impacting live alert generation.
Question: Where are Wazuh custom decoders stored?
Custom decoders are typically stored in:
/var/ossec/etc/decoders/
This location helps separate custom content from the default Wazuh ruleset.
Question: Why does Logtest succeed but alerts are not generated?
If Logtest shows successful decoding but alerts never appear, investigate:
- Rule configuration
- Alert levels
- Rule dependencies
- Indexing issues
- Dashboard visibility problems
The decoder may be working correctly while another stage in the pipeline is failing.
Question: Do I need to restart Wazuh after creating a new decoder?
In most environments, yes.
New decoder definitions generally require the manager to reload the updated ruleset before they become available.
Always review startup logs afterward to confirm successful loading.
Question: How can I see which decoder matched a log?
Run the event through Logtest and review Phase 2 output.
Example:
name: 'custom_auth_decoder'
This identifies the decoder that processed the event.
Question: What is the fastest way to troubleshoot a non-matching decoder?
A reliable troubleshooting workflow is:
- Verify raw log format.
- Check Phase 1 pre-decoding output.
- Validate prematch conditions.
- Test regex extraction.
- Confirm parent decoder behavior.
- Review manager logs.
- Validate rule execution.
This method systematically eliminates the most common causes of decoder failure.
Conclusion
Custom decoder matching failures are among the most common challenges encountered when developing Wazuh detections.
Fortunately, most issues fall into a relatively small set of categories that can be diagnosed methodically.
Throughout this guide, we examined the most frequent causes of decoder failures, including:
- Incorrect regular expressions
- Prematch mismatches
- Parent decoder dependency issues
- Decoder loading failures
- Precedence conflicts
- Program name mismatches
- XML configuration errors
- Log formatting and special-character problems
A key takeaway is that decoder troubleshooting should always begin with Wazuh Logtest.
Its three-phase output provides invaluable visibility into pre-decoding, decoding, and rule evaluation, allowing you to pinpoint exactly where processing breaks down.
A recommended troubleshooting workflow is:
- Capture the raw production log.
- Review Phase 1 pre-decoding output.
- Verify prematch conditions.
- Validate regex matching and field extraction.
- Confirm parent-child decoder relationships.
- Check manager startup and analysis logs.
- Test dependent rules.
- Validate end-to-end alert generation.
Following this structured process eliminates guesswork and significantly reduces troubleshooting time.
As your Wazuh deployment grows, focus on building decoders that are simple, well-documented, thoroughly tested, and maintained through version control.
Combined with regular regression testing and post-upgrade validation, these practices will help ensure your custom detections remain reliable and effective long after deployment.
For additional decoder and detection-engineering guidance, you may also find these resources helpful:
Be First to Comment