---
title: "Troubleshooting"
manual: "Temporal Cache Management"
version: "main"
source: "Configuration/Troubleshooting.rst"
rendered: "2026-10-07T14:40:31+00:00"
---

# Troubleshooting {#configuration-troubleshooting}

Diagnose and resolve common configuration issues.

## Start here {#configuration-troubleshooting-first}

```bash
vendor/bin/typo3 temporalcache:verify
```

The command checks the indexes and columns the queries need, the two strategy
names, and the time slots when harmonization is enabled.
It reports which check failed and exits with 1.
See [Verifying the setup](Advanced.html#configuration-advanced-verify) for the full list of checks.

## Cache not updating {#configuration-troubleshooting-not-updating}

**Symptoms**

-   Temporal content does not appear or disappear at the scheduled time
-   Menus show pages whose `starttime` has not been reached

**Checks**

1.  **Which timing strategy is active?**

    ```bash
    vendor/bin/typo3 temporalcache:analyze
    ```

    Only `dynamic` expires the cache by itself.
    `scheduler` relies entirely on the scheduler task, and `hybrid` does for
    whichever content type is routed to it, so check that the task exists in the
    Scheduler module and that cron is running it.
    See [Scheduler task](Advanced.html#scheduler-setup).
1.  **Do the indexes exist?**

    The extension ships them in [`ext_tables.sql`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/ExtTablesSql.html#file-extension-ext-tables-sql); TYPO3 creates them
    during the database compare, not at installation time.

    ```sql
    SHOW INDEX FROM pages WHERE Key_name LIKE 'idx_temporalcache%';
    SHOW INDEX FROM tt_content WHERE Key_name LIKE 'idx_temporalcache%';
    ```

    Expected on both tables: `idx_temporalcache_starttime` over
    `(starttime, sys_language_uid)` and `idx_temporalcache_endtime` over
    `(endtime, sys_language_uid)`.
    If they are missing, run the database compare rather than creating them by
    hand:

    ```bash
    vendor/bin/typo3 extension:setup
    ```

    **Admin Tools → Maintenance → Analyze Database Structure** does the
    same from the backend.
1.  **Is the record actually visible?**

    The transition queries skip records that are deleted or hidden, and they
    filter on the language of the current context.
    A hidden record's `starttime` never triggers anything.
1.  **Turn on debug logging.**

    ```text
    advanced.debug_logging = 1
    ```

    ```bash
    grep TemporalCache var/log/typo3_*.log | tail -50
    ```

    With `dynamic` timing, one entry per page cache generation shows the
    lifetime that was written and which maximum capped it.

## High database load {#configuration-troubleshooting-performance}

**Symptoms**

-   Slow page generation with `timing.strategy = dynamic`
-   Many `MIN(starttime)` / `MIN(endtime)` queries in the slow query log

**What the extension queries**

The dynamic strategy runs two `MIN()` queries per monitored table — one for
`starttime`, one for `endtime` — on every page cache generation.
With the two default tables that is four queries.
Each table registered through `TemporalMonitorRegistry` adds two more.

The site-wide lookup used by `global` and `per-content` scoping is cached
for the duration of the request; the two lookups of `per-page` scoping are
not.

**Options**

1.  Make sure the indexes above exist — without them these are full table scans.
1.  Set `timing.strategy = scheduler` to remove the queries from page
    generation entirely.
    This needs the scheduler task; read [Scheduler task](Advanced.html#scheduler-setup) first.
1.  Check the query plan:

    ```sql
    EXPLAIN SELECT MIN(starttime) FROM pages
    WHERE starttime > UNIX_TIMESTAMP()
      AND hidden = 0 AND deleted = 0
      AND sys_language_uid IN (0, -1);
    ```

    The plan should use one of the `idx_temporalcache_*` indexes instead of
    scanning the table.

Changing `scoping.strategy` does not reduce this load: under dynamic timing
every scoping strategy performs the same kind of lookup, and `per-content`
performs the site-wide one.

## Harmonization not working {#configuration-troubleshooting-harmonization}

**Symptoms**

-   The Content tab shows no harmonization column or no suggestions
-   Timestamps stay where they were

**Checks**

1.  `harmonization.enabled = 1`.
    While it is off, the service returns every timestamp unchanged and the
    backend module hides the column.
1.  The slots parse.
    Entries must be `HH:MM` or `H:MM` with hours 0-23 and minutes 0-59;
    anything else is
    dropped silently, and with no valid slot left nothing is harmonized.
    `temporalcache:verify` reports the parsed slots when harmonization is
    enabled.
1.  The tolerance is large enough.
    A timestamp is only moved when its nearest slot is at most
    `harmonization.tolerance` seconds away.

    ```text
    Slots 00:00,12:00 with tolerance 3600:

    11:30 → nearest slot 12:00, 30 min away  → harmonized to 12:00
    10:30 → nearest slot 12:00, 90 min away  → left at 10:30
    ```

    `harmonization.tolerance = 0` harmonizes nothing at all: no timestamp is
    ever within a distance of zero of a slot unless it already sits on one.
    `temporalcache:verify` reports it as `ROUNDING OFF` rather than as an
    error, because switching rounding off is a valid choice.
1.  The distance is measured on the circular day.
    23:30 is 30 minutes from a `00:00` slot, because the nearest occurrence of
    that slot is the next day's.
1.  Harmonization is invoked, not automatic.
    Nothing rewrites timestamps when an editor saves a record.
    Use **Harmonize selected** in **Tools → Temporal Cache →
    Content**, or:

    ```bash
    vendor/bin/typo3 temporalcache:harmonize
    ```

## Scheduler task {#configuration-troubleshooting-scheduler}

[`ext_localconf.php`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/ExtLocalconf.html#file-extension-ext-localconf-php) registers the task type, so **Scheduler →
Create new task** offers **Temporal Cache: Process transitions**.
Registering the type is not the same as scheduling it — see
[Scheduler task](Advanced.html#scheduler-setup).

If transitions are not processed, verify that the task exists and that the
Scheduler itself runs:

```bash
crontab -l | grep scheduler
vendor/bin/typo3 scheduler:run
```

## Configuration not taking effect {#configuration-troubleshooting-values}

**Typos in strategy names are not errors.**
`ScopingStrategyFactory` and `TimingStrategyFactory` activate the strategy
whose name matches the configured value and fall back to the highest-priority
tagged strategy — `global` and `dynamic` — when none does.
A misspelled `per-contnet` therefore behaves exactly like the default.
`temporalcache:verify` flags both values as `INVALID`.

**Out-of-range values are clamped, not rejected.**
`advanced.default_max_lifetime` of 0 or less is skipped in favour of 86400.

**Two configuration sources.**
The Extension Manager writes to `config/system/settings.php`;
`config/system/additional.php` is read afterwards, so an assignment there
overrides the Extension Manager value.
Check both files before concluding that a setting is ignored.

## Getting help {#configuration-troubleshooting-help}

Collect before reporting:

```bash
vendor/bin/typo3 extension:list | grep temporal_cache
vendor/bin/typo3 temporalcache:verify
vendor/bin/typo3 temporalcache:analyze
grep TemporalCache var/log/typo3_*.log | tail -50
```

Report at [GitHub issues](https://github.com/netresearch/t3x-nr-temporal-cache/issues) with the TYPO3
version, the extension version and the output above.

## Next steps {#next-steps}

-   [Optimization strategies](Strategies.html#configuration-strategies) \- What each setting does
-   [Examples & presets](Examples.html#configuration-examples) \- Complete configuration examples
-   [Dashboard](../Backend/Dashboard.html#backend-dashboard) \- What the backend module reports
-   [Performance considerations](../Performance/Index.html#performance-considerations) \- Performance implications