🚨 Filebeat Error Guide: 'Can only start an input when all related states are finished' — Fix Overlapping Inputs

Overview

Filebeat logs this warning when it tries to start a harvester for a file whose state is still owned by another, not-yet-finished input:

Can only start an input when all related states are finished: {Id: native::12345-2049, Finished: false, Fileinfo: ... Source: /var/log/app/app.log ...}

Every file Filebeat reads has a state in the registry keyed by its inode/device. Two inputs whose paths: globs both match the same file will both try to claim that state. Filebeat allows only one active harvester per file state, so the second input’s start is blocked until the first releases the state (marked Finished: true). The result is that a file is read by the wrong input, read late, or effectively not read by the input you expected.

Symptoms

• Repeated warnings containing Can only start an input when all related states are finished.
• A file’s events carry the fields/tags of the wrong input, because another input grabbed it first.
• Some files are harvested inconsistently or with delay after config reloads.
• The warning spikes right after adding a new input whose path overlaps an existing one.
• Duplicate or missing lines around file rotation.

Common Root Causes

• Overlapping paths: globs across inputs — e.g. one input matches /var/log/app/*.log and another matches /var/log/app/app.log.
• The same path listed in two input blocks, sometimes via a broad /var/log/**/*.log catch-all plus a specific input.
• A harvester that never finishes because close_* options keep it open, so the state is never released.
• Config reload racing — an input restarted before the previous harvester closed its file.
• Symlinks resolving two globs to one real file.

Diagnostic Workflow

Find which inputs claim the same file by listing every input’s resolved paths, then eliminate the overlap.

filebeat export config -c /etc/filebeat/filebeat.yml | grep -A3 'paths'
grep -rn 'paths' /etc/filebeat/filebeat.yml /etc/filebeat/inputs.d/ 2>/dev/null

Give each input a unique, non-overlapping scope and a stable id:

# /etc/filebeat/filebeat.yml
filebeat.inputs:
  - type: filestream
    id: app-main
    paths:
      - /var/log/app/app.log        # specific
    fields: { source: app-main }

  - type: filestream
    id: app-workers
    paths:
      - /var/log/app/worker-*.log   # disjoint from app.log
    fields: { source: app-workers }

filebeat test config -c /etc/filebeat/filebeat.yml
filebeat -e -c /etc/filebeat/filebeat.yml -d "input,harvester"   # watch state ownership

Example Root Cause Analysis

An operator added a “catch-all” input to grab anything under /var/log/app/ while keeping the original specific input for app.log:

- type: filestream
  id: app-specific
  paths: ["/var/log/app/app.log"]

- type: filestream
  id: app-catchall
  paths: ["/var/log/app/*.log"]     # ALSO matches app.log

Both inputs matched app.log. Whichever started first owned the state; the other logged Can only start an input when all related states are finished on every scan, and app.log events sometimes arrived tagged as app-catchall. The fix was to make the globs disjoint by excluding the specific file from the catch-all:

- type: filestream
  id: app-catchall
  paths: ["/var/log/app/*.log"]
  prospector.scanner.exclude_files: ['/var/log/app/app\.log$']

With no overlap, each file mapped to exactly one input and the warnings stopped.

Prevention Best Practices

• Keep every input’s paths: glob mutually exclusive; never let two inputs match the same file.
• Prefer specific patterns over broad ** catch-alls, or use exclude_files to carve out already-claimed paths.
• Give each filestream input a unique, stable id so state ownership is unambiguous.
• Avoid symlinks in log directories that can make two globs resolve to one real file.
• After adding an input, run filebeat export config and eyeball the resolved paths for overlap before deploying.

Quick Command Reference

filebeat export config | grep -A3 'paths'          # list all resolved input paths
grep -rn 'paths' /etc/filebeat/                     # find overlapping globs
filebeat -e -d "input,harvester"                    # debug state ownership live
# fix: make globs disjoint or use prospector.scanner.exclude_files
filebeat test config                                # validate after editing

Conclusion

This warning means two inputs are fighting over the same file’s state. Filebeat permits only one harvester per file, so overlapping paths: globs cause blocked starts and mis-tagged events. Map every file to exactly one input — tighten globs or add exclude_files to carve out already-claimed paths — and give each input a stable id. Reviewing the output of filebeat export config for path overlap before deploying prevents the conflict entirely.