[Bug] core:archive incorrectly counts cron/flock wrapper processes as concurrent archivers

[duakayra]

What happened?

When core:archive is executed by a cron job wrapped with flock and shell processes, Matomo incorrectly counts the wrapper processes as separate concurrent archivers.

The cron job creates a process tree similar to:

/bin/sh
  -> /usr/bin/flock
     -> /bin/bash
        -> php83 .../matomo/console core:archive

Only the final PHP process is an actual Matomo archiver.

However, in core/CronArchive.php, hasReachedMaxConcurrentArchivers() counts every process whose command line contains both:

strpos($process, ' core:archive') !== false &&
strpos($process, 'console ') !== false

Since the parent shell and flock processes contain the complete child command in their arguments, all four processes match.

Matomo therefore reports:

Archiving will stop now because 4 archivers are already running and max 3 are supposed to run at once.
Reached maximum concurrent archivers allowed (3), aborting run.

The same core:archive command executed directly from the shell works normally and reports:

1 out of 3 archivers running currently

This occurs on Hetzner hosting, where frequent cron jobs are wrapped/protected with flock to prevent overlapping executions.

Related discussion about Hetzner's cron/flock requirement:
contao/contao#9404

What should happen?

A single core:archive invocation should be counted as one concurrent archiver, regardless of whether it is started through cron, flock, or shell wrapper processes.

Matomo should distinguish the actual PHP core:archive process from parent processes whose command-line arguments merely contain the text console core:archive.

The current behavior prevents scheduled report archiving from running, even though only one real Matomo archiver exists.

As a workaround, moving the actual core:archive command into a separate executable shell script and having flock execute only that script prevents the wrapper processes from containing console core:archive.

How can this be reproduced?

Configure a cron job where core:archive is executed through flock and a shell, for example:

05 * * * * '/usr/bin/flock' -n -E 0 '/path/to/archive.lck' '/bin/bash' -c '/usr/bin/php /path/to/matomo/console core:archive --url="https://stats.example.com/" >> /path/to/matomo-archive.log'

When the cron job runs, inspect matching processes:

ps -eo pid,ppid,args | grep 'core:archive' | grep 'console '

In our case one cron execution produced:

80572 80569 /bin/sh -c '/usr/bin/flock' ... '/bin/bash' -c '/usr/bin/php .../matomo/console core:archive ...'
80575 80572 /usr/bin/flock ... /bin/bash -c /usr/bin/php .../matomo/console core:archive ...
80577 80575 /bin/bash -c /usr/bin/php .../matomo/console core:archive ...
80580 80577 php83 ... /matomo/console core:archive ...

There is only one actual PHP archiver, but all four command lines contain console core:archive.

Matomo then reports:

Archiving will stop now because 4 archivers are already running and max 3 are supposed to run at once.
Reached maximum concurrent archivers allowed (3), aborting run.

For comparison, running the underlying command directly:

/usr/bin/php /path/to/matomo/console core:archive --url="https://stats.example.com/"

results in:

1 out of 3 archivers running currently

and archiving completes successfully.

Matomo version

5.13.0

PHP version

8.3

Server operating system

Debian GNU/Linux 12 (bookworm)

What browsers are you seeing the problem on?

No response

Computer operating system

No response

Relevant log output

INFO      [2026-08-28 10:05:02] 80580  Running Matomo 5.13.0 as Super User
INFO      [2026-08-28 10:05:02] 80580  Async process archiving supported, using CliMulti.
INFO      [2026-08-28 10:05:02] 80580  Starting Matomo reports archiving...
INFO      [2026-08-28 10:05:02] 80580  Archiving will stop now because 4 archivers are already running and max 3 are supposed to run at once.
INFO      [2026-08-28 10:05:02] 80580  Reached maximum concurrent archivers allowed (3), aborting run.

Process list captured during the same cron invocation:

80572 80569 /bin/sh -c '/usr/bin/flock' ... '/bin/bash' -c '/usr/bin/php .../matomo/console core:archive ...'
80575 80572 /usr/bin/flock ... /bin/bash -c /usr/bin/php .../matomo/console core:archive ...
80577 80575 /bin/bash -c /usr/bin/php .../matomo/console core:archive ...
80580 80577 php83 ... /matomo/console core:archive ...

Validations

• Read our Contributing Guidelines.
• Follow our Security Policy.
• Check that there isn't already an issue that reports the same bug to avoid creating duplicates.
• The provided steps to reproduce is a minimal reproducible of the Bug.

[des-innocraft]

@duakayra

Thanks for the detailed report. We confirmed that Matomo currently identifies running archivers by searching the process list for console core:archive. When the command is started through cron, flock, and shell wrappers, those parent processes can contain the same command text and may therefore be counted as additional archivers.

We confirmed that Matomo currently counts some wrapper processes created by cron, flock, or the shell as archivers. This behavior is documented in the --concurrent-archivers help text, and we are proposing an enhancement to make Matomo distinguish the actual PHP archiver process from these wrappers.

As a workaround, you can:

• Put the core:archive command in a separate executable shell script and have flock execute that script.
• Increase --concurrent-archivers to account for the additional wrapper entries. In the example provided, setting it to at least 4 should prevent the single actual archiver from being stopped by the limit.

The second workaround should be used carefully, since increasing the limit may allow more real archivers to run concurrently than intended if multiple jobs overlap. Running the command through a separate script is the safer workaround.

Let us know if this works.