Resolving Filebeat Registry File Locked Errors on Wazuh Managers

If you’re encountering the “registry file locked” error on a Wazuh manager, Filebeat is unable to access its registry database, preventing it from tracking which log entries have already been processed.

Since Filebeat is responsible for forwarding alerts from the Wazuh manager to the Wazuh Indexer, a locked registry file can interrupt the entire log ingestion pipeline, resulting in delayed or missing security events.

The Filebeat registry file is a small but critical database that stores the current read position (offset) for every monitored log file. Instead of re-reading entire log files after every restart, Filebeat consults this registry to resume exactly where it left off.

This mechanism improves performance while preventing duplicate event ingestion.

Registry file lock errors typically occur when another Filebeat process is already using the registry, the service terminates unexpectedly and leaves stale lock information behind, file permissions become corrupted, or the underlying storage experiences locking problems.

Administrators may also encounter these errors after restoring backups, cloning virtual machines, or manually manipulating Filebeat’s data directory.

Common symptoms include log messages such as “registry file locked,” “cannot obtain lock on registry,” or “failed to initialize registrar.”

In many cases, the Filebeat service repeatedly crashes and restarts, Wazuh alerts stop appearing in the dashboard, and log ingestion falls behind.

In this guide, you’ll learn how the Filebeat registry works, why registry lock errors occur on Wazuh managers, how to diagnose the underlying cause, and several proven methods to safely restore normal log forwarding without losing event data.

Understanding the Wazuh Filebeat Registry File

What Is the Filebeat Registry File?

The Filebeat registry is a local state database that records how far Filebeat has progressed while reading each monitored log file.

Every time Filebeat harvests new log entries, it updates the registry with the latest file offset so it knows exactly where to resume after a restart.

Without this registry, Filebeat would either:

Re-read entire log files, creating duplicate events.
Skip portions of log files, resulting in lost security events.

This registry acts as Filebeat’s memory, ensuring reliable and continuous log collection.

According to Elastic’s Filebeat documentation, the registry stores persistent state information that enables reliable harvesting across restarts and prevents duplicate processing of previously collected log entries.

Tracks Harvested Log File Offsets

Each monitored log file has an associated offset stored in the registry.

Whenever new data is written to a log, Filebeat resumes reading from the last recorded byte position instead of scanning the file from the beginning.

This becomes especially important on busy Wazuh managers where:

Thousands of security events are generated every minute.
Log files rotate frequently.
Multiple log sources are harvested simultaneously.

Maintaining accurate offsets minimizes processing overhead while ensuring every event is shipped exactly once.

Prevents Duplicate Log Ingestion

One of the registry’s primary responsibilities is preventing duplicate log forwarding.

For example:

Filebeat reads the first 500 MB of a log file.
The service restarts.
Instead of processing those 500 MB again, Filebeat resumes from the stored offset.

Without this behavior, the Wazuh Indexer would receive duplicate alerts, increasing storage usage and producing inaccurate dashboards.

If you’re also troubleshooting indexing issues, see How to Fix circuit_breaking_exception Data Overloads in Wazuh Indexer.

Location of the Registry File on Linux Installations

On most Wazuh manager installations using modern Filebeat versions, the registry data is stored under:

/var/lib/filebeat/

Depending on the Filebeat version, you’ll commonly find files such as:

/var/lib/filebeat/registry/
/var/lib/filebeat/registry/filebeat/

Older Filebeat releases may use slightly different directory structures, but the registry is typically located within Filebeat’s data directory.

Administrators should avoid manually editing registry files while Filebeat is running because doing so can corrupt the stored state.

Relationship Between Filebeat and the Wazuh Indexer

Within a Wazuh deployment, Filebeat serves as the transport layer between the Wazuh manager and the Wazuh Indexer.

The workflow generally looks like this:

Wazuh Manager generates alerts.
Alerts are written to log files.
Filebeat monitors those files.
Registry tracks reading progress.
Filebeat forwards alerts to the Wazuh Indexer.
The Wazuh Dashboard displays indexed security events.

If the registry becomes locked, Filebeat cannot continue harvesting logs, breaking this pipeline and preventing new alerts from reaching the indexer.

If Filebeat cannot establish communication with the manager or indexer, see Resolving Filebeat Connection Refused Errors in Wazuh Deployments.

Why the Registry File Becomes Locked

Registry locking is a protection mechanism designed to ensure that only one Filebeat process writes to the registry database at any given time.

While this prevents corruption, several conditions can leave the registry inaccessible.

Multiple Filebeat Instances Running Simultaneously

The most common cause is multiple Filebeat processes attempting to use the same registry.

This often happens when:

Filebeat is started manually while the systemd service is already running.
Automation scripts accidentally launch duplicate instances.
Containers mount the same registry directory.
Failover scripts start Filebeat without verifying existing processes.

Since the registry supports only one writer, additional processes immediately fail with a lock error.

Improper Shutdowns

Unexpected shutdowns can leave Filebeat without properly releasing registry resources.

Examples include:

Power failures
Kernel panics
Forced process termination (kill -9)
Virtual machine crashes
Unexpected operating system reboots

Although Filebeat usually recovers automatically, abrupt termination may occasionally leave stale locking information.

Stale Lock Files

If Filebeat exits unexpectedly, lock metadata may remain even though no active process is using the registry.

Administrators often encounter this after:

Interrupted upgrades
Backup restoration
Filesystem recovery
Manual copying of the Filebeat data directory

Care should be taken to verify that no Filebeat process is actually running before removing stale lock information.

File System Permission Issues

Filebeat must have read and write access to its registry directory.

Permission problems can arise from:

Manual ownership changes
Incorrect chmod or chown operations
SELinux restrictions
AppArmor policies
Deployment automation mistakes

When Filebeat cannot create or update lock files, initialization fails.

Elastic recommends ensuring that the Filebeat data directory remains writable by the Filebeat service account.

Network Storage or NFS-Related Locking Problems

Running the Filebeat registry on network-mounted storage can introduce file locking inconsistencies.

NFS environments may experience:

Delayed lock propagation
Lost file locks
Temporary network interruptions
Inconsistent cache synchronization

Because Filebeat relies on reliable local file locking, placing the registry on shared storage is generally discouraged.

The NFS version 4 specification discusses standardized network file locking behavior and its limitations across distributed systems.

Disk Corruption or I/O Errors

Underlying storage failures may also prevent registry access.

Examples include:

Bad sectors
SSD failures
Filesystem corruption
Read/write I/O errors
Full disks

When Filebeat cannot safely read or update its registry, it refuses to start rather than risking state corruption.

Common Symptoms of a Locked Filebeat Registry

Typical Error Messages

Registry locking problems usually appear immediately when Filebeat starts.

Common log messages include:

registry file locked

cannot obtain lock on registry

failed to initialize registrar

Depending on the Filebeat version, additional startup errors may accompany these messages, indicating that the registrar could not access its persistent state database.

Filebeat Repeatedly Restarting

If Filebeat is managed by systemd, repeated startup failures often trigger automatic restart attempts.

Administrators may observe:

Filebeat starts.
Registry initialization fails.
Service exits.
Systemd immediately retries.
The cycle repeats indefinitely.

This restart loop continues until the underlying registry issue is resolved.

Operational Symptoms

Even when administrators do not immediately notice startup errors, several operational problems quickly become apparent.

Logs Stop Reaching the Wazuh Indexer

Since Filebeat is responsible for forwarding alerts from the Wazuh manager, registry lock failures halt log shipping entirely.

As a result:

New alerts never reach the indexer.
Existing dashboards stop updating.
Detection rules appear inactive.
Event timelines contain unexpected gaps.

Missing Alerts in the Wazuh Dashboard

One of the earliest warning signs is that the Wazuh Dashboard stops displaying recent security events.

You may notice:

Empty dashboards
Stale timestamps
Missing agent activity
Delayed incident visibility

If the dashboard itself also shows loading or indexing issues, see Wazuh Dashboard Not Loading? Complete Troubleshooting Guide.

Filebeat Service Enters a Restart Loop

System administrators frequently discover the problem by checking service status.

Typical indicators include:

High restart counters
Frequent service failures
Short-lived Filebeat processes
Continuous journal log entries

Persistent restart loops also generate unnecessary CPU usage and excessive log noise, making it more difficult to identify unrelated infrastructure problems.

Increased Log Shipping Delays

Even if Filebeat eventually acquires the registry lock after several retries, administrators may still experience delayed log delivery.

These delays can result in:

Slower threat detection
Delayed alert correlation
Increased indexing latency
Temporary gaps in monitoring coverage

Because Wazuh depends on timely event delivery for effective security monitoring, resolving registry lock issues promptly helps maintain accurate, real-time visibility across your environment.

Common Causes of Wazuh Filebeat Registry Lock Errors

While the error message simply reports that the registry is locked, the underlying cause can vary significantly.

Identifying the root cause before attempting a fix reduces the risk of registry corruption or unnecessary data loss.

Multiple Filebeat Processes

The most common cause of registry lock errors is having more than one Filebeat process attempting to use the same registry simultaneously.

Because Filebeat uses an exclusive file lock to protect the registry database, only one process can access it at a time.

Duplicate Services

Duplicate services can occur after:

Manual service creation
Configuration management mistakes
Multiple systemd unit files
Package upgrade conflicts

In these situations, two Filebeat services may start during boot, with one successfully obtaining the registry lock while the other immediately fails.

Manual Filebeat Execution

Administrators often start Filebeat manually while the system service is already running.

For example:

sudo filebeat -e

If the systemd service already owns the registry, the manually started instance will fail with a registry lock error.

This frequently happens during troubleshooting when administrators forget to stop the existing service first.

Automation Conflicts

Automation platforms can accidentally launch duplicate Filebeat instances.

Examples include:

Ansible playbooks
Puppet manifests
Chef recipes
Kubernetes startup scripts
Custom shell scripts
Cron jobs

Poor coordination between automation tools and systemd can create intermittent registry lock issues that are difficult to reproduce.

Stale Lock Files

Occasionally, the registry appears locked even though no Filebeat process is actively using it.

This is usually caused by stale lock metadata left behind after an abnormal shutdown.

Unexpected Crashes

Unexpected operating system crashes may prevent Filebeat from releasing its registry lock cleanly.

Examples include:

Kernel panics
Hypervisor failures
Sudden power loss
Hardware resets

Although Filebeat is designed to recover gracefully, abrupt interruptions can occasionally leave inconsistent registry state.

Forced Process Termination

Using commands such as:

kill -9 <PID>

immediately terminates Filebeat without allowing it to perform cleanup operations.

Whenever possible, stop Filebeat gracefully through systemd before resorting to forceful termination.

Interrupted Upgrades

Registry locking issues sometimes appear after interrupted software upgrades.

Possible causes include:

Upgrade cancellation
Package manager failures
Reboots during installation
Version rollback attempts

If Filebeat was updating its registry during the interruption, cleanup may not complete successfully.

Incorrect File Ownership or Permissions

Even when no process owns the registry lock, Filebeat must still be able to create, modify, and remove registry files.

Permission problems are a frequent source of initialization failures.

Registry Owned by the Wrong User

This often happens after:

Restoring backups
Copying registry files manually
Running Filebeat as root once
Changing service accounts

If the registry becomes owned by another user, the Filebeat service account may lose write access.

SELinux or AppArmor Restrictions

Mandatory Access Control (MAC) frameworks can also prevent Filebeat from accessing its registry.

Depending on policy configuration, SELinux or AppArmor may block:

File creation
File locking
Registry updates
Directory access

Audit logs often provide additional information when these security policies are responsible.

Directory Permission Problems

Sometimes the registry file itself has correct permissions while the parent directory does not.

Administrators should verify permissions on:

/var/lib/filebeat
Registry subdirectories
Parent directories
Mounted filesystems

Without execute permissions on parent directories, Filebeat cannot access otherwise readable files.

Corrupted Registry Files

A damaged registry database may prevent Filebeat from acquiring or validating its lock.

Power Failures

Sudden power loss while Filebeat is updating the registry can leave partially written registry data.

Modern filesystems reduce this risk but cannot eliminate it completely.

Disk Write Interruptions

Storage interruptions may occur because of:

Failing SSDs
RAID controller problems
SAN interruptions
Virtual disk failures

Partial writes can damage registry metadata.

File System Corruption

Filesystem corruption may prevent Filebeat from reading registry files correctly.

Possible indicators include:

I/O errors
Bad inode references
Filesystem inconsistencies
Failed filesystem checks

These problems typically require repairing the underlying filesystem before Filebeat can operate normally.

Shared Storage Issues

The Filebeat registry is designed for local storage rather than shared storage environments.

Using unsupported storage architectures can introduce locking conflicts.

Unsupported Network File Systems

Network file systems may not fully support Filebeat’s locking requirements.

Examples include:

NFS
CIFS/SMB
Distributed file systems
Cloud-mounted storage

Even when locking appears functional, latency and caching can cause inconsistent behavior.

Cluster Storage Conflicts

Some administrators mistakenly place multiple Wazuh managers on shared storage so they access a common Filebeat registry.

This configuration is unsupported because Filebeat expects exclusive ownership of its registry.

Concurrent Access from Multiple Nodes

If multiple servers attempt to read and update the same registry simultaneously, locking failures are almost guaranteed.

Each Wazuh manager should maintain its own independent Filebeat data directory and registry database.

How to Diagnose the Problem

Before deleting registry files or restarting services, determine exactly why the registry is locked.

A systematic diagnosis helps prevent unnecessary data loss and avoids masking the real issue.

Check the Filebeat Service Status

Start by confirming whether Filebeat is actually running.

On most Linux systems:

sudo systemctl status filebeat

Review the service status for startup failures, restart loops, and recent error messages.

Verify Service Health

Look for indicators such as:

Active (running)
Failed
Activating
Restarting

A healthy service should remain continuously active without frequent restarts.

Identify Restart Failures

If systemd repeatedly attempts to restart Filebeat, you’ll often see messages indicating consecutive failures or restart counters increasing rapidly.

These failures usually coincide with registry initialization errors.

Search the Filebeat Logs

The Filebeat logs typically contain the most detailed information about registry-related failures.

For systems using systemd:

sudo journalctl -u filebeat

You can also inspect Filebeat log files directly if logging is configured to write to disk.

Locate Registrar Errors

Search for terms such as:

registrar
registry
lock
state
initialization

Registrar-related errors usually pinpoint the exact stage where startup failed.

Confirm Registry Locking Messages

Common log entries include:

registry file locked
cannot obtain lock on registry
failed to initialize registrar

Confirming these messages helps distinguish registry issues from unrelated configuration problems.

Check for Multiple Filebeat Processes

Multiple Filebeat instances are one of the easiest causes to verify.

Use:

ps -ef | grep filebeat

pgrep -a filebeat

Only one active Filebeat process should normally appear.

Verify Only One Process Is Running

If multiple Filebeat processes are listed, identify which one was started by systemd and which may have been started manually.

Duplicate processes nearly always explain registry lock errors.

Identify Orphaned Processes

Occasionally, Filebeat processes remain running even though the service reports as stopped.

These orphaned processes continue holding the registry lock until terminated.

Inspect Open File Handles

If no duplicate processes are obvious, determine which process currently owns the registry file.

Use lsof

The lsof utility lists processes that have a file open.

Example:

sudo lsof /var/lib/filebeat/registry/*

This command identifies the process currently accessing the registry.

Use fuser

Alternatively:

sudo fuser -v /var/lib/filebeat/registry/*

This displays the process IDs currently using the registry files.

Determine Which Process Owns the Lock

Once the owning process is identified, determine whether it is:

The legitimate Filebeat service
A duplicate Filebeat instance
An orphaned process
Another application unexpectedly accessing the registry

Verify Registry File Permissions

Incorrect ownership or permissions can prevent Filebeat from opening the registry.

Inspect the registry directory:

ls -lah /var/lib/filebeat

Ownership

Verify that the registry files belong to the Filebeat service account.

Unexpected ownership often results from manual file operations or restored backups.

Permissions

Ensure the registry files are writable by the Filebeat service while remaining appropriately protected from unauthorized users.

Parent Directory Access

Don’t overlook directory permissions.

Even correctly owned registry files cannot be accessed if parent directories lack execute permissions.

Check Available Disk Space

A completely full filesystem can prevent Filebeat from updating its registry.

Check available space:

df -h

Ensure Sufficient Free Space

Leave adequate free space for:

Registry updates
Log rotation
Temporary files
System operations

Running out of disk space can trigger a variety of Filebeat startup failures.

Detect Read-Only File Systems

Also verify that the filesystem has not been remounted as read-only following disk errors.

Attempting to update a registry on a read-only filesystem always fails.

Verify File System Health

If registry problems persist despite correct permissions and a single Filebeat process, investigate storage health.

I/O Errors

Kernel logs may report:

Input/output errors
Device failures
Filesystem warnings
Read failures

These messages often indicate hardware or filesystem problems.

Kernel Log Messages

Inspect recent kernel logs:

dmesg | grep -i -E "error|ext4|xfs|disk|i/o"

Storage-related errors frequently appear here before affecting Filebeat.

Storage Hardware Issues

Persistent registry corruption can indicate underlying hardware failures such as:

Failing SSDs
RAID degradation
Controller failures
Virtual disk problems

Resolving storage issues is essential before rebuilding the Filebeat registry.

How to Fix Wazuh Filebeat Registry File Locked Errors

Once you’ve identified the root cause, follow these steps to safely restore Filebeat operation without unnecessarily risking data loss.

Stop the Filebeat Service Safely

Always stop Filebeat before modifying registry files.

sudo systemctl stop filebeat

This ensures no active process is writing to the registry.

Prevent Further Registry Access

Confirm that no automation or monitoring tools immediately restart Filebeat while maintenance is underway.

Temporary disabling of restart policies may be appropriate in some environments.

Confirm Shutdown

Verify that Filebeat has fully stopped:

sudo systemctl status filebeat

pgrep filebeat

No running Filebeat processes should remain.

Terminate Orphaned Filebeat Processes

If Filebeat processes continue running after the service stops, terminate them manually.

Locate Lingering Processes

Use:

ps -ef | grep filebeat

Review each process carefully before terminating it.

Remove Stale Processes Safely

Terminate lingering processes gracefully whenever possible.

Only use forceful termination if the process refuses to exit normally.

Remove Stale Lock Files

If no Filebeat process is running, stale lock files may safely be removed.

Confirm Filebeat Is Stopped First

Double-check that every Filebeat process has exited before deleting any registry lock information.

Removing lock files while Filebeat is active can corrupt the registry.

Delete Only Obsolete Lock Files

Avoid deleting the entire registry unless corruption has been confirmed.

Instead, remove only obsolete lock files associated with the registry.

Verify Lock Removal

Inspect the registry directory afterward to confirm the stale lock has been removed.

Correct Registry File Permissions

Restore proper ownership and permissions if access problems are detected.

Restore Ownership

Reset ownership to the Filebeat service account using the appropriate chown command for your environment.

Reset Permissions

Ensure the registry directory and files have appropriate read and write permissions without being unnecessarily permissive.

Validate Access

Before restarting Filebeat, verify that the service account can successfully access the registry directory.

Repair or Rebuild the Registry File

If the registry is corrupted beyond repair, rebuilding it may be necessary.

Backup the Registry

Before making changes, create a backup of the existing registry directory.

This provides a recovery point if further troubleshooting is required.

Remove Corrupted Registry Data

After creating a backup, remove the corrupted registry data so Filebeat can initialize a clean registry during startup.

Allow Filebeat to Recreate It

When Filebeat starts, it automatically creates a new registry if none exists.

The service will begin tracking monitored log files from its configured starting point.

Understand Potential Duplicate Ingestion

Depending on your Filebeat configuration, rebuilding the registry may cause previously processed log entries to be ingested again.

Plan accordingly if duplicate events could affect reporting or downstream workflows.

Restart Filebeat

After completing repairs, restart the service.

sudo systemctl start filebeat

Confirm Successful Startup

Verify that Filebeat remains active:

sudo systemctl status filebeat

There should be no registry-related errors during initialization.

Verify Registry Initialization

Review the Filebeat logs to confirm the registrar starts successfully and the registry is opened without lock errors.

Validate Log Shipping

The final step is ensuring that log forwarding has resumed normally.

Confirm Events Reach the Wazuh Indexer

Verify that new alerts are successfully indexed and searchable.

If indexing problems persist after Filebeat is repaired, see How to Fix a Yellow Cluster Status in Wazuh Indexer and How to Fix circuit_breaking_exception Data Overloads in Wazuh Indexer.

Verify New Alerts Appear in the Dashboard

Generate a test event and confirm that it appears in the Wazuh Dashboard within a reasonable timeframe.

Successful event delivery indicates that the registry has been rebuilt or unlocked correctly and that Filebeat has resumed normal communication with the Wazuh Indexer.

Advanced Troubleshooting

If the standard recovery steps do not resolve the problem, more advanced investigation is required.

Persistent registry lock errors often indicate deeper issues involving process management, storage, or deployment architecture.

Registry Lock Persists After Restart

If the registry remains locked even after restarting Filebeat or rebooting the server, another process or system component may still be holding the lock.

Hidden Filebeat Processes

Not every Filebeat process is immediately visible from a simple service status check.

Use multiple utilities to verify running processes:

ps -ef | grep filebeat

pgrep -a filebeat

pstree -p | grep filebeat

Compare the process IDs with the systemd service to determine whether an unexpected instance is still active.

Service Manager Conflicts

In some environments, more than one service manager may attempt to control Filebeat simultaneously.

Examples include:

systemd
Supervisor
Docker restart policies
Kubernetes controllers
Third-party monitoring agents

If one manager stops Filebeat while another immediately restarts it, registry lock conflicts can occur repeatedly.

Review all service definitions and automation tools to ensure only one component manages the Filebeat lifecycle.

Zombie Processes

Although zombie processes do not typically hold file locks, orphaned parent processes sometimes leave child processes running unexpectedly.

Inspect the process tree carefully to identify lingering Filebeat-related processes that survived an interrupted shutdown.

Filebeat Starts but Stops Again

Sometimes the registry lock disappears, but Filebeat still exits shortly after startup.

This usually indicates an unrelated issue that only becomes visible after the registry problem has been resolved.

Configuration Validation

Before investigating further, validate the Filebeat configuration.

sudo filebeat test config

Configuration errors involving:

Incorrect YAML syntax
Invalid modules
Missing certificates
Incorrect output settings

can all prevent Filebeat from remaining operational.

If configuration errors are present, resolve them before restarting the service.

Output Connectivity

Even with a healthy registry, Filebeat must successfully connect to its output destination.

Verify connectivity to:

Wazuh Indexer
Network interfaces
TLS certificates
Authentication credentials

Connectivity problems may cause Filebeat to terminate shortly after startup.

If Filebeat cannot communicate with the indexer, see Resolving Filebeat Connection Refused Errors in Wazuh Deployments.

Resource Limitations

Insufficient system resources can also cause repeated service failures.

Investigate:

Available RAM
CPU utilization
Open file descriptor limits
Disk space
System load

Resource exhaustion may prevent Filebeat from maintaining normal operation, particularly on busy Wazuh managers processing large volumes of security events.

Registry Rebuild Causes Duplicate Events

One concern administrators often have is duplicate alerts after rebuilding the registry.

This behavior is expected under certain conditions.

Why Duplicates Occur

When the registry is removed or recreated, Filebeat no longer knows which portions of monitored log files have already been processed.

Depending on its configuration, it may begin reading existing log files again, causing previously indexed events to be forwarded a second time.

How Filebeat Resumes Harvesting

Filebeat determines its starting position based on:

Registry state
Input configuration
Existing log file metadata
File modification timestamps

A newly created registry starts with no historical state, requiring Filebeat to rebuild its tracking information.

Minimizing Duplicate Ingestion

To reduce duplicate events:

Back up the registry before rebuilding it.
Rebuild the registry only when corruption is confirmed.
Avoid deleting registry data during routine troubleshooting.
Perform maintenance during low-traffic periods.
Monitor newly indexed events after restarting Filebeat.

If duplicate events are unavoidable, they are generally preferable to losing security logs altogether.

Lock Errors on Clustered Wazuh Managers

Clustered deployments introduce additional considerations for Filebeat management.

Independent Filebeat Instances

Each Wazuh manager should run its own Filebeat instance with its own dedicated registry directory.

Every node should maintain independent harvesting state to avoid synchronization conflicts.

Shared Storage Pitfalls

Sharing a single Filebeat registry between cluster nodes is unsupported.

Potential issues include:

Lock contention
Registry corruption
Duplicate ingestion
Lost file offsets
Inconsistent harvesting state

Whenever possible, store Filebeat data on local storage attached to each Wazuh manager.

Cluster Deployment Considerations

For clustered environments:

Maintain identical Filebeat configurations where appropriate.
Keep registry directories local to each node.
Synchronize configuration changes carefully.
Monitor each manager independently.
Verify Filebeat health after cluster upgrades.

If you’re managing a clustered deployment, see How to Build a Wazuh Indexer Cluster and Fixing Wazuh Cluster Desync Caused by Master-Worker Time Drift.

Preventing Future Registry Lock Errors

Preventive maintenance significantly reduces the likelihood of registry lock problems and helps maintain uninterrupted log forwarding.

Always Stop Filebeat Gracefully

Whenever possible, stop Filebeat using the system’s service manager instead of forcefully terminating the process.

Proper Service Shutdown Procedures

On most Linux distributions:

sudo systemctl stop filebeat

This allows Filebeat to:

Flush buffered events
Update the registry
Release file locks
Exit cleanly

Avoid Forced Process Termination

Avoid using commands such as:

kill -9

except as a last resort.

Forceful termination bypasses Filebeat’s cleanup routines and increases the likelihood of stale registry locks.

Avoid Running Multiple Instances

Only one Filebeat process should manage a registry at any given time.

Verify Startup Scripts

Review custom startup scripts for accidental duplicate launches.

Look for:

Manual filebeat commands
Duplicate cron jobs
Initialization scripts
Container entrypoints

Review Automation Tools

Automation platforms should start and stop Filebeat consistently.

Verify that tools such as:

Ansible
Puppet
Chef
SaltStack

are not launching additional Filebeat processes outside the system service.

Prevent Duplicate Services

Check for duplicate service definitions:

systemctl list-unit-files | grep filebeat

Only one active Filebeat service should exist on each manager.

Monitor Filebeat Health

Continuous monitoring allows administrators to detect registry issues before they interrupt security monitoring.

Service Monitoring

Track:

Service uptime
Restart count
Process health
Resource utilization

Most enterprise monitoring platforms can alert when Filebeat becomes unhealthy.

Alert on Repeated Restarts

Repeated restarts often indicate registry locking, configuration problems, or connectivity failures.

Configure alerts whenever Filebeat exceeds a defined restart threshold.

Watch Registrar Errors

Search Filebeat logs for registrar-related warnings, including:

registry
registrar
state
lock
initialization

Early detection allows corrective action before log ingestion stops completely.

Keep Filebeat Updated

Running supported versions of Filebeat improves stability and compatibility.

Bug Fixes

New releases frequently resolve:

Registry handling bugs
Lock management issues
Memory leaks
Stability problems

Review release notes before upgrading production systems.

Lock Handling Improvements

Registry management has evolved significantly across Filebeat releases.

Later versions include improvements in:

Registry reliability
Recovery after crashes
Lock acquisition
Registrar performance

Compatibility with Wazuh Releases

Ensure the installed Filebeat version is supported by your Wazuh release.

Using unsupported version combinations can introduce unexpected operational issues.

For broader platform maintenance guidance, see How to Upgrade a Wazuh Agent.

Maintain Healthy Storage

Reliable storage is essential for a healthy Filebeat registry.

Monitor Disk Usage

Track disk utilization regularly to prevent full filesystems from interrupting registry updates.

Detect File System Issues Early

Investigate storage warnings promptly, including:

I/O errors
SMART alerts
Filesystem inconsistencies
Read-only remounts

Resolving storage issues early helps prevent registry corruption.

Schedule Storage Health Checks

Routine filesystem checks and hardware monitoring help identify failing storage before it impacts log collection.

Regularly Back Up Configuration

Although the registry itself is temporary state information, Filebeat’s configuration should always be backed up.

Preserve Filebeat Settings

Maintain backups of:

filebeat.yml
TLS certificates
Custom modules
Output configuration
Input definitions

These backups simplify disaster recovery.

Document Registry Recovery Procedures

Create documented recovery procedures covering:

Service shutdown
Registry backup
Registry rebuild
Validation steps
Post-recovery verification

Standardized procedures reduce recovery time during future incidents.

Best Practices for Managing Filebeat on Wazuh Managers

Following operational best practices minimizes downtime and helps maintain consistent log delivery across your Wazuh deployment.

Use Consistent Configuration Across Managers

Standardize Filebeat configurations across all Wazuh managers whenever possible.

Configuration consistency reduces:

Deployment errors
Troubleshooting complexity
Version drift
Unexpected behavior between nodes

Version control systems can help track configuration changes over time.

Validate Configuration Before Restarting Services

Always validate configuration changes before restarting Filebeat.

sudo filebeat test config

This simple step catches syntax errors and invalid settings before they interrupt production log shipping.

Monitor Filebeat Logs Continuously

Regularly review Filebeat logs for:

Registry warnings
Connection failures
TLS errors
Registrar issues
Unexpected restarts

Proactive log monitoring allows administrators to detect emerging problems long before they impact the Wazuh Dashboard.

Elastic recommends monitoring Filebeat logs as part of routine operational maintenance to quickly identify ingestion and registrar issues.

Restrict Manual Service Operations

Limit manual starting and stopping of Filebeat to authorized administrators.

Whenever possible:

Use standardized operational procedures.
Avoid running Filebeat directly from the command line on production servers.
Perform changes through documented maintenance processes.

Reducing manual intervention lowers the risk of duplicate processes and registry lock conflicts.

Schedule Routine Maintenance Windows

Perform upgrades, configuration changes, and registry maintenance during planned maintenance windows.

This allows administrators to:

Verify successful startup
Monitor log ingestion
Confirm dashboard functionality
Roll back changes if necessary

Planned maintenance minimizes operational risk and reduces the likelihood of missed security events.

Keep Operating Systems Updated

Operating system updates often include important improvements affecting:

Filesystem reliability
Process management
Storage drivers
Security patches

Maintaining supported operating system versions improves the overall stability of Filebeat and the Wazuh manager.

Test Changes in a Non-Production Environment

Before deploying major Filebeat changes to production:

Validate new configurations in a staging environment.
Test registry recovery procedures.
Simulate service failures.
Verify successful log forwarding after recovery.

Testing changes ahead of time reduces the likelihood of unexpected outages and helps ensure that production Wazuh managers continue delivering security events reliably.

Frequently Asked Questions (FAQ)

Question: What does “registry file locked” mean in Filebeat?

The “registry file locked” error means that Filebeat cannot obtain exclusive access to its registry database.

The registry stores the current read position for each monitored log file, allowing Filebeat to resume harvesting without reprocessing previously collected events.

This error usually indicates one of the following:

Another Filebeat instance is already running.
A stale lock remains after an improper shutdown.
The registry directory has permission issues.
The registry file is corrupted.
The underlying storage cannot provide reliable file locking.

Until the lock issue is resolved, Filebeat cannot initialize its registrar, and log forwarding to the Wazuh Indexer will typically stop.

Question: Is it safe to delete the Filebeat registry file?

Yes, but only as a last resort.

If the registry has become corrupted and cannot be repaired, removing it allows Filebeat to create a new registry during startup.

However, deleting the registry has consequences:

Filebeat loses its harvesting history.
Previously processed log files may be read again.
Duplicate events may be indexed.
Initial log processing may take longer.

Always:

Stop the Filebeat service.
Back up the existing registry.
Confirm corruption before deleting it.

Avoid removing the registry simply because a lock error appears, as the underlying issue may instead be a duplicate process or permission problem.

Question: Can multiple Filebeat processes run on the same Wazuh manager?

Technically, yes. But they should not share the same registry.

If two Filebeat processes attempt to access the same registry directory simultaneously, one process will successfully acquire the lock while the other fails with a registry lock error.

If multiple Filebeat instances are required for specialized workloads, each instance should have its own:

Configuration file
Data directory
Registry location
Log directory

For standard Wazuh deployments, a single Filebeat service is the recommended configuration.

Question: Why does the registry lock return after every reboot?

If the problem reappears after every reboot, the issue is usually environmental rather than temporary.

Common causes include:

Duplicate startup services
Automation scripts launching additional Filebeat instances
Incorrect service configuration
Shared storage mounting problems
Permission changes applied during startup
Filesystem inconsistencies

Instead of repeatedly deleting lock files, investigate why the registry is becoming locked during system initialization.

Review startup scripts, automation tools, and service definitions to identify recurring conflicts.

Question: Will rebuilding the registry cause duplicate log ingestion?

It can.

When Filebeat creates a new registry, it no longer knows which portions of monitored log files have already been processed.

Depending on your Filebeat configuration and the state of existing log files, it may re-read previously harvested data, resulting in duplicate events being forwarded to the Wazuh Indexer.

The likelihood of duplicates depends on factors such as:

Filebeat input settings
Log rotation status
Existing file metadata
Registry removal timing

To minimize duplicate ingestion, rebuild the registry only when corruption has been confirmed and always create a backup beforehand.

Question: How can I determine which process owns the registry lock?

Linux provides several utilities for identifying which process currently has the registry open.

Useful commands include:

sudo lsof /var/lib/filebeat/registry/*

sudo fuser -v /var/lib/filebeat/registry/*

You can also verify running Filebeat processes using:

pgrep -a filebeat

or:

ps -ef | grep filebeat

These commands help determine whether the registry is being used by:

The legitimate Filebeat service
A duplicate Filebeat process
An orphaned process
Another unexpected application

Question: Does this error affect Wazuh alert generation?

Yes.

The Wazuh manager will generally continue generating alerts internally, but Filebeat is responsible for forwarding those alerts to the Wazuh Indexer.

If Filebeat cannot start because its registry is locked:

Alerts are not shipped to the indexer.
The Wazuh Dashboard stops receiving new events.
Searches return incomplete results.
Security analysts may lose visibility into ongoing activity until Filebeat resumes normal operation.

For this reason, registry lock errors should be addressed as quickly as possible to avoid monitoring gaps.

Conclusion

The “wazuh filebeat registry file locked” error is most commonly caused by duplicate Filebeat processes, stale registry locks, incorrect file permissions, corrupted registry data, or storage-related issues.

Although the error prevents Filebeat from starting, it is usually straightforward to resolve once the underlying cause has been identified.

Effective troubleshooting begins by verifying the Filebeat service status, reviewing Filebeat logs, checking for multiple running processes, inspecting registry ownership and permissions, and evaluating the health of the underlying storage.

In more severe cases, rebuilding the registry may be necessary, but this should only be done after creating a backup and confirming that simpler solutions are not sufficient.

Long-term stability depends on proactive maintenance.

Running only one Filebeat instance per registry, shutting down services gracefully, monitoring registrar errors, maintaining healthy storage, validating configuration changes before deployment, and keeping both Filebeat and Wazuh up to date will significantly reduce the likelihood of future registry lock issues.

For related Wazuh troubleshooting topics, you may also find these guides useful:

By following the diagnostic steps, recovery procedures, and best practices outlined in this guide, you can restore reliable log collection and help ensure that your Wazuh managers continue delivering timely security events to the Wazuh Indexer and Dashboard.