---
title: "Upgrade Wizards"
manual: "Grid Elements"
version: "main"
permalink: "https://docs.typo3.org/permalink/gridelementsteam/gridelements:upgradingcompatibilityupgradewizards@main"
source: "Chapters/UpgradingCompatibility/UpgradeWizards/Index.rst"
rendered: "2026-11-04T14:20:48+00:00"
---

# Upgrade Wizards {#upgradingcompatibilityupgradewizards}

Grid Elements does not register a TYPO3 Install Tool upgrade wizard
(`UpgradeWizardInterface`) for its own data; there is no entry for
it in Admin Tools > Upgrade (TYPO3 13) or System > Upgrade (TYPO3 14).
The mechanisms that exist for repairing
Grid Elements' own fields after something has gone wrong are the two
data consistency tools documented in full at
[Data Consistency Tools](https://docs.typo3.org/permalink/gridelementsteam/gridelements:dataconsistencytools@main): the Col Pos Fixer and the Number Of
Children Fixer, each available as both a TYPO3 CLI command and a
classic Scheduler task.

## No structural migration between Grid Elements versions {#no-structural-migration-between-grid-elements-versions}

The absence of a registered upgrade wizard is not only about repair
tooling; it also reflects that upgrading Grid Elements itself has not
required one. Grid Elements' persisted structure,
`tx_gridelements_container` as the parent relation,
`tx_gridelements_columns` as the structural cell, and
`tx_gridelements_children` as the maintained IRRE counter, see
[Data Model](https://docs.typo3.org/permalink/gridelementsteam/gridelements:datamodel@main), has remained backward-compatible across Grid
Elements versions. An existing Grid Elements structure continues to be
understood by a newer Grid Elements version without being converted
into a replacement structural storage model.

This is distinct from the two other mechanisms on this page and in
this section:

-   **Structural migration** would convert existing data from one
    structural model to another. Grid Elements has not required this
    between its own versions.
-   **Repair and consistency tools**, the Col Pos Fixer and Number Of
    Children Fixer described below, restore specific field values after
    an external interference. They repair values within the existing
    structural model; they do not convert it into a different one.
-   **Compatibility-related Upgrade Wizards**, see
    [Data Compatibility Across TYPO3 Versions](https://docs.typo3.org/permalink/gridelementsteam/gridelements:upgradingcompatibilitydatacompatibility@main), address how Grid
    Elements' data interacts with a given TYPO3 Core version, such as
    the `colPos` schema definition. This is not a statement that no
    TYPO3 Core-level upgrade wizard is ever relevant to a project using
    Grid Elements, only that none is required to migrate the Grid
    Elements structure itself.

## When they are actually relevant {#when-they-are-actually-relevant}

Both tools exist for exceptional states, not as a routine step in
every upgrade. The Col Pos Fixer's own docblock names the scenario
that makes it relevant specifically to upgrading: a TYPO3 Core
major-version upgrade running while Grid Elements is temporarily
uninstalled or inactive, so its `ext_tables.sql` schema definition
is not part of the active set a schema migration compares against, and
the migration applies Core's unsigned `colPos` definition instead of
Grid Elements' own. This is purely a database schema mechanism, see
[Data Compatibility Across TYPO3 Versions](https://docs.typo3.org/permalink/gridelementsteam/gridelements:upgradingcompatibilitydatacompatibility@main); it is separate from
this tool, which only repairs the resulting record values, not the
column's SQL definition. That scenario is avoidable, not an inherent
part of upgrading: Grid Elements does not need to be deactivated for a
Core major-version upgrade, since each maintained version already
supports both the TYPO3 version it targets and its predecessor at the
same time, see [Data Compatibility Across TYPO3 Versions](https://docs.typo3.org/permalink/gridelementsteam/gridelements:upgradingcompatibilitydatacompatibility@main) for why.
This tool exists for the case where that avoidable step happened
anyway, most often through a hosting provider's own automated upgrade
tooling. The Number Of Children Fixer is not upgrade-specific; it
repairs a maintained counter that can drift from unrelated
cut/copy/paste or drag-and-drop edge cases at any time, upgrade or
not.

Neither tool needs to run automatically as part of an upgrade
pipeline. Run them, via CLI or a one-off Scheduler execution, only
after a known interference with `tt_content` such as the upgrade
scenario above, or when a specific report of a wrong `colPos`
sentinel or a wrong `tx_gridelements_children` count cannot be
explained by normal backend editing. Both are idempotent: rerunning
either one against already-correct data changes nothing.

## What they modify {#what-they-modify}

| Tool | Modifies |
| --- | --- |
| Col Pos Fixer | `tt_content.colPos`, unconditionally set back to `-1` for every row that currently has `tx_gridelements_container > 0`. It does not touch the relation itself; if `tx_gridelements_container` was also lost, this tool cannot recover it. |
| Number Of Children Fixer | `tt_content.tx_gridelements_children` on every `gridelements_pi1` container, recomputed from an actual count of rows whose `tx_gridelements_container` points at it. |

See [Data Consistency Tools](https://docs.typo3.org/permalink/gridelementsteam/gridelements:dataconsistencytools@main) for the exact commands, task classes
and SQL each tool runs.
