How to Manage Cron Jobs with TYPO3 Scheduler (Complete 2026 Guide)

Quick Summary - How TYPO3 Scheduler & Cron Work Together

TYPO3 Scheduler is the core system for automating recurring tasks in your TYPO3 site, from clearing caches and logs to sending newsletters.

To ensure tasks run automatically, you link the Scheduler to your server’s cron job:

Linux / Unix:

*/15 * * * * /usr/local/bin/php /path/to/typo3/sysext/core/bin/typo3 scheduler:run

Windows (Task Scheduler):

schtasks /create /sc minute /mo 15 /tn "TYPO3 Scheduler" /tr "C:\path\to\php.exe C:\path\to\typo3\sysext\core\bin\typo3 scheduler:run"

When to use manual CLI runs:

• Testing a new task before scheduling
• Debugging failed or delayed tasks
• Running tasks outside their regular frequency for special maintenance

What Is TYPO3 Scheduler? Explained for Admins & Devs

TYPO3 Scheduler is a core TYPO3 extension that automates and executes recurring tasks on your website. It allows administrators and developers to schedule routine operations, reducing manual work and ensuring site maintenance runs reliably.

Key Uses of TYPO3 Scheduler

Scheduler can handle a wide range of automated tasks, including:

• Sending newsletters to customers
• Deleting outdated images or files
• Clearing caches and performing garbage collection
• Optimizing the MySQL database regularly
• Removing old logs and system entries

How Scheduler Tasks Are Queued and Run

• Tasks are created in the backend and assigned a schedule frequency.
• Once triggered (via cron or manual execution), TYPO3 queues the tasks and executes them sequentially.
• Each task runs independently, with error logging available for debugging.

Why It Matters: By automating these repetitive processes, TYPO3 Scheduler keeps your site clean, fast, and optimized, while freeing up administrator time.

How TYPO3 Scheduler Architecture Works (Technical Walkthrough)

TYPO3 Scheduler is designed to centralize task execution and relies on a single cron job to trigger all scheduled tasks. Understanding this architecture ensures you configure your server correctly and avoid missed or duplicate task runs.

1. Single Cron Event Triggers All Tasks

• Instead of scheduling each task individually at the system level, TYPO3 uses one cron job that calls the Scheduler script at a defined interval.
• This cron call queues and executes all active tasks according to their schedule within TYPO3.

2. Backend Manual Run vs Cron Job Execution

3. Task Lifecycle

1. Task Creation – Admin or developer creates a task in the backend or via CLI.
2. Scheduling – Task is assigned a frequency (daily, hourly, weekly).
3. Queued Execution – On cron trigger, TYPO3 Scheduler checks which tasks are due and queues them.
4. Execution & Logging – Tasks are executed sequentially; success or errors are logged for debugging.
5. Repeat – Tasks return to the queue for the next scheduled run.

4. TYPO3 Scheduler CLI Commands (Basics)

Composer-based TYPO3 Setup:

php vendor/bin/typo3 scheduler:run

Without Composer:

php typo3/sysext/core/bin/typo3 scheduler:run

Check PHP CLI Path (Linux/Unix):

which php
/usr/local/bin/php typo3/sysext/core/bin/typo3 scheduler:run

Get Help for Scheduler Command:

vendor/bin/typo3 scheduler:run --help

Run Single Task:

vendor/bin/typo3 scheduler:run --task=1

Run Multiple Tasks:

vendor/bin/typo3 scheduler:run --task=1 --task=2

Force Run Task:

vendor/bin/typo3 scheduler:run --task=1 -f

Debug Task (Verbose Mode, Recommended):

vendor/bin/typo3 scheduler:run --task=1 -v

TYPO3 Scheduler Terminology Glossary

Understanding TYPO3 Scheduler requires familiarity with key terms used in task management, cron integration, and CLI commands.

Scheduler Task

A unit of work defined in TYPO3 Scheduler. Each task performs a specific automated action, such as clearing caches, sending emails, or optimizing the database.

Frequency vs Interval

• Frequency: How often the task is scheduled to run (e.g., daily, hourly).
• Interval: The exact time between task executions (e.g., every 15 minutes).
   Tip: Correctly configuring frequency and interval prevents missed tasks or overloading the server.

Execution Timestamps

The recorded times when a task was last executed and when it is next scheduled. Useful for auditing and debugging task execution.

Task Group

A way to organize multiple tasks under a single category or group. Helps administrators manage and prioritize related tasks efficiently.

Console Command Hook

A method to trigger custom tasks via CLI or Symfony console commands. This enables advanced automation and integration with other TYPO3 extensions.

Priority Queue

Scheduler can assign tasks different priorities, ensuring critical tasks run first. Lower-priority tasks are queued and executed after higher-priority ones

Brief History of TYPO3 Scheduler

TYPO3 Scheduler originated from the “Gabriel” extension, initially developed by Christian Jul Jensen and later enhanced by Markus Friedrich. Over time, it became a core part of TYPO3, enabling administrators and developers to automate recurring tasks directly within the CMS.

Since TYPO3 v9, Scheduler gained Symfony console integration, making task automation more powerful and flexible.

Why it matters: Understanding its evolution helps admins appreciate its design, reliability, and integration capabilities in modern TYPO3 installations.

Installing & Enabling TYPO3 Scheduler

TYPO3 Scheduler is included by default in the TYPO3 core. However, on some installations, the extension may not be activated. Follow these steps to ensure Scheduler is installed and configured correctly.

Composer Installation (Recommended for Modern TYPO3)

If your site uses Composer, install the Scheduler extension with:

composer require typo3/cms-scheduler

After installation, clear caches and ensure the extension is loaded.

Activating Scheduler via Admin UI

For non-Composer installations, or if Scheduler is already present:

1. Log in to TYPO3 backend.
2. Go to Admin Tools > Extensions.
3. Locate the Scheduler extension and click Activate.

Configuration of TYPO3 Scheduler

Once activated, configure Scheduler settings:

1. Navigate to Admin Tools > Settings > Extensions Configuration > Scheduler.
2. Adjust default task settings such as email notifications, logging, and execution timeouts.

Common Pitfalls

• Scheduler not appearing in backend: check that the extension is installed and activated.
• PHP CLI path issues: ensure the path matches your server configuration.
• Permissions errors: the backend user must have appropriate access to Scheduler tasks.

Preparing TYPO3 Scheduler – Pre‑Check Diagnostics

Before scheduling tasks, it’s important to verify that TYPO3 Scheduler is working correctly. This ensures your tasks will run reliably when triggered by cron or manually.

Step 1: Run the Setup Check

1. Log in to the TYPO3 backend.
2. Navigate to System > Scheduler.
3. Choose “Setup Check”.

Tip: If any warnings or errors appear, contact your system administrator or check server configurations. Common issues include:

• Missing PHP CLI path
• Incorrect permissions for the Scheduler user
• Disabled Scheduler extension

Step 2: Create a Test Task

To confirm that Scheduler executes tasks correctly:

• Go to System > Scheduler > Information.

• Click the “+” button to add a new task.
• Fill in required fields: task type, frequency, email for notifications, etc.

• Click Save & Close.

Step 3: Manually Execute the Task

• Navigate to System > Scheduler > Scheduled Tasks.

• Click the Run Task button.

• Verify execution by checking logs or notification emails.

Optional: Stop a running task by clicking Stop Scheduler.

Manually Stop TYPO3 Scheduler Task

• Step 1. Go to System > Scheduler > Scheduled Tasks
• Step 2. Click on the “Stop Scheduler” button.

Step 4: Organize Tasks Using Task Groups

• Assign tasks to groups for easier management.

• Helps prioritize important tasks and keep multiple scheduled jobs organized.

• Task groups also simplify reporting and troubleshooting.

TYPO3 Scheduler CLI Command Cheat Sheet

The main command to run Scheduler tasks is:

vendor/bin/typo3 scheduler:run

Common flags and their use:

Tips:

• Use verbose mode -v to debug task execution.
• Force execution -f is useful for testing failed tasks.
• Always verify PHP CLI path matches your server configuration.

When to Run Scheduler Manually

Manual execution is recommended in these cases:

• Testing a new task before scheduling it automatically.
• Debugging failed or delayed tasks.
• Running a task outside its regular frequency for maintenance or emergency updates.

How Cron Works with TYPO3 Scheduler (Server Level)

Automating TYPO3 Scheduler tasks requires configuring a cron job (on Linux/Unix) or Task Scheduler (on Windows). Below are step-by-step instructions for different environments, along with best practices and common pitfalls.

Linux / Unix Cron Job Setup (Best Practices)

1. Edit your crontab
    Open your terminal and run:
   
    crontab -e
    

2. Add the Scheduler command

    */15 * * * * /usr/local/bin/php /www/typo3/sysext/core/bin/typo3 scheduler:run

   • Runs every 15 minutes (recommended).
   • Adjust frequency based on your tasks:
     • */5 → very frequent, for critical tasks
     • */15 → standard, safe for most sites
     • 0 0 * * * → daily tasks

3. Use the correct user for shared servers

    */15 * * * * www /usr/local/bin/php /www/typo3/sysext/core/bin/typo3 scheduler:run

Tips:

• Verify the PHP CLI path with which php.
• Avoid overly frequent execution to prevent server overload.
• Ensure the cron user has proper file and directory permissions.

Windows Task Scheduler Example

1. Open Task Scheduler
   • Press Win + R, type taskschd.msc, and press Enter.

2. Create a new task
    Run the following command in Command Prompt to schedule it:

    schtasks /create /sc minute /mo 15 /tn "TYPO3 Scheduler" /tr “C:\path\to\php.exe C:\path\to\typo3\sysext\core\bin\typo3 scheduler:run”

   • Adjust /mo 15 to set the frequency in minutes.

Common Pitfalls on Windows:

• PHP CLI path must match your installation.
• Task must run under a user with access to TYPO3 directories.
• Avoid overlapping tasks to prevent conflicts.

Hosting Panel Cron (cPanel / Plesk / DirectAdmin)

1. Log in to your hosting panel and navigate to the Cron Jobs section.
2. Add a new cron job with the command:
    /usr/local/bin/php /path/to/typo3/sysext/core/bin/typo3 scheduler:run
3. Set the frequency
   • Recommended: every 15 minutes (*/15 * * * *).
   • Most panels provide dropdowns for minute/hour/day settings.

Tips:

• Use the correct user, commonly www-data or your hosting account user.
• Test the cron job manually before scheduling.
• Review logs regularly to confirm successful execution.

Known Issues / Troubleshooting

• Some running tasks cannot be killed because the Scheduler process PID may not link to the cron process.
• Manual intervention may be needed for stuck tasks.
• Always enable logging and email notifications to track failed or delayed tasks.

Why This Setup Matters:
Configuring cron properly ensures your TYPO3 Scheduler tasks run automatically, reliably, and without manual intervention. Following best practices prevents common pitfalls like overlapping tasks, permission issues, or missed executions.

Why TYPO3 Doesn’t Auto-Run Tasks

• TYPO3 Scheduler is part of the CMS, not a persistent background service.
• Tasks are only executed when the Scheduler script is called via cron or manual CLI execution.
• This design ensures that tasks run in a controlled environment with proper permissions and logging.

Cron vs Systemd Timer

Key Points:

• Regardless of method, a single cron or systemd trigger executes all scheduled tasks in TYPO3.
• Proper configuration ensures reliable, repeatable, and logged executions.
• Avoid running multiple triggers simultaneously to prevent overlapping tasks.

Tips for Server Setup:

• Always verify that the PHP CLI path matches your server configuration using which php.
• Run test tasks manually before enabling the cron or timer to ensure proper execution.
• Use logging and email notifications to monitor task success and failures.

Expert Execution & Automations with TYPO3 Scheduler

To get the most out of TYPO3 Scheduler, it’s important to organize tasks, schedule essential jobs, and leverage Symfony CLI for advanced automation. Below is a comprehensive guide.

Best Practices for Scheduler Task Groups

Organizing tasks into groups ensures clarity, efficiency, and easier troubleshooting.

Recommendations:

• Naming Conventions: Use descriptive names such as Cache Cleanup or Newsletter Dispatch.
• Priority Grouping: Assign high-priority tasks (e.g., database optimization) to run first.
• Task Categorization: Group related tasks such as file cleanup, caching, or logs.

Tip: Task groups make reporting and debugging easier when many tasks are scheduled.

Recommended Essential Tasks to Schedule

For an optimized TYPO3 instance, configure the following tasks:

• TYPO3 Garbage Collection – Remove unnecessary records from system tables.
• Caching Cleanup – Clear caches to improve site performance.
• Fileadmin Garbage Collection – Remove unused files and assets.
• Logs Cleanup (sys_log) – Maintain system log tables for better performance.
• History Cleanup (sys_history) – Keep your database neat and lightweight.
• Database Optimization – Schedule periodic MySQL optimizations.
• Search Index Refresh – Keep full-text search accurate and up-to-date.

These tasks ensure your TYPO3 instance remains clean, fast, and reliable.

Custom Scheduler Tasks with Symfony Console

TYPO3 Scheduler allows you to create custom tasks using Symfony console commands. These tasks can be executed manually via CLI or scheduled via cron for full automation.

18. Creating Custom Scheduler Tasks

Step 1: Register Symfony Console Commands

Create a Services.yaml file inside your extension: (typo3conf/ext/yourextension/Configuration/Services.yaml):

services:
_defaults:
  autowire: true
  autoconfigure: true
  public: false

Vendor\Extension\Command\TestScheduler:
  tags:
    - name: "console.command"
      command: "myext:test"
      description: "An example description for a command"
      hidden: false

Tip:

• autowire and autoconfigure ensure your services are automatically recognized by TYPO3.
• The hidden flag controls whether the command appears in --help.

Step 2: Create Scheduler Command Controller Class

Create the command class in typo3conf/ext/yourextension/Classes/Command/TestScheduler.php:

<?php
namespace Vendor\Extension\Command;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

class TestScheduler extends Command
{
  protected function configure()
  {
      $this
          ->setDescription('Test Scheduler')
          ->setHelp('Description of the test scheduler')
          ->addArgument('id', InputArgument::OPTIONAL, 'Task ID');
  }

  protected function execute(InputInterface $input, OutputInterface $output)
  {
      $io = new SymfonyStyle($input, $output);
      $id = $input->getArgument('id');

      if (!$id) {
          $io->error('No id provided');
      } else {
          $io->success('Successfully run id=' . $id);
      }

      return Command::SUCCESS;
  }
}

Why it matters: This class defines the logic for your custom task and integrates seamlessly with TYPO3 Scheduler.

Step 3: Create a TYPO3 Scheduler Task

• Go to System > Scheduler > Add New Task.

• Choose Class = Execute Console Commands.
• Select your custom command, e.g., myext:test TYPO3 Scheduler.

• Configure frequency, email notifications, and task group if needed.

Step 4: Test the Command via CLI

For Composer-based TYPO3 installations:

composer dump-autoload
vendor/bin/typo3 myext:test
vendor/bin/typo3 myext:test id=1

Without arguments, the command runs the default behavior.

Help Command:

vendor/bin/typo3 myext:test -h

Step 5: Schedule via Cron

Add the task to your server’s cron:

crontab -e
*/15 * * * * /usr/local/bin/php /www/typo3/sysext/core/bin/typo3 myext:test

Tip: Adjust the frequency to match the criticality of the task.

Running Custom Tasks from Cron

• Pass arguments directly in the cron command if needed:

/usr/local/bin/php /www/typo3/sysext/core/bin/typo3 myext:test id=5

• Multiple tasks can be chained with --task flags.

Approval & Testing Workflows for Custom Tasks

• Test Coverage: Always test tasks on a development or staging server before scheduling on production.
• Monitoring: Enable logging and email notifications to track execution success or failures.
• Deployment: After verifying on staging, schedule cron on production and continue monitoring for issues.

Monitoring & Reporting Scheduler Output

• Email Notifications: Inform admins about critical task completion or failures.
• Logging: Use TYPO3’s logging framework for detailed execution reports.
• Monitoring Tools: Optional integration with Grafana, Prometheus, or server logs for continuous tracking.

Tip: Regular monitoring prevents missed executions and allows proactive troubleshooting.

Common Cron Scheduler Errors & Fixes

Even when TYPO3 Scheduler is configured correctly, issues usually happen at the handoff between the backend task setup and the server-side trigger.

In TYPO3 14.3, the official docs recommend starting with Setup Check, which shows when the scheduler last ran and warns you if it has never run at all. TYPO3 also provides scheduler:list, scheduler:run, and scheduler:execute for command-line troubleshooting.

• sssCron never fires
  • Run Setup Check in Scheduler and confirm TYPO3 shows a recent run.
  • Test the command manually with vendor/bin/typo3 scheduler:run.
  • Use scheduler:list to confirm the task exists and is available.
• Task runs but no action happens
  • Check whether the task isdisabled.
  • Check next execution time and whether it is a one-time task.
  • Check whether parallel execution is blocking it.
  • Review Administration > Log for task errors.
• Permission issues
  • Make sure the cron user can access the TYPO3 files, PHP binary, and required directories.
  • Check whether the task is stuck inrunning state.
  • Revie Maximum lifetime if crashed tasks stay locked too long.
• PHP CLI path errors
  • Verify the exact PHP CLI path used by cron.
  • Confirm you are using the correct TYPO3 CLI path for your setup.
  • Re-run Setup Check after updating cron.
• Known limitation
  • A running task cannot always be safely killed because TYPO3 may not reliably map it to the cron process.
  • Use forced stopping only as a last resort.

Security Considerations

• CLI user vs web user
  • Run cron with a dedicated user that has only the permissions the task needs.
  • Do not give broad write access unless required.
• Secure cron permissions
  • Limit access to TYPO3 files, logs, and import folders.
  • Review task ownership and execution rights regularly.
• Avoiding task injection
  • Mark sensitive commands as non-schedulable when they should not appear in Scheduler.
  • Validate all command arguments before file or database operations.
  • Avoid scheduling commands that expect interactive input.

Performance Tips

• How Scheduler impacts site performance
  • Performance issues usually come from heavy tasks, short intervals, or overlapping runs.
  • Recurring tasks deny parallel execution by default unless you allow it.
• Queue management best practices
  • Use short intervals only for critical jobs.
  • Run cleanup and maintenance tasks less frequently.
  • Keep parallel execution disabled unless overlap is proven safe.
  • Monitor blocked, failed, or delayed tasks in the Scheduler backend and logs.
  • Set a sensible Maximum lifetime so stuck tasks do not block future runs.

Conclusion

TYPO3 Scheduler is a powerful built-in tool for automating recurring tasks, improving maintenance, and keeping your TYPO3 installation running efficiently. From basic task management and cron job setup to custom Symfony console commands, it gives administrators and developers the flexibility to handle both routine and advanced automation needs.

With the right setup, regular monitoring, and a few essential maintenance tasks in place, you can keep your TYPO3 instance clean, stable, and easier to manage. If you run into issues while configuring TYPO3 Scheduler or creating custom tasks, use the troubleshooting steps in this guide to identify and fix them quickly.

If you still have questions or want to share your experience with TYPO3 Scheduler, feel free to leave a comment.