---
title: "Feature: \"academic:upgrade:check\" finds dead overrides"
manual: "Academic Base"
version: "main"
permalink: "https://docs.typo3.org/permalink/fgtclb/academic-base:feature-upgrade-check-command@main"
source: "Changelog/3.0/Feature-UpgradeCheckCommand.rst"
rendered: "2026-10-17T08:47:46+00:00"
---

# Feature: "academic:upgrade:check" finds dead overrides {#feature-upgrade-check-command}

## Description {#description}

`EXT:academic_base` ships the console command
`academic:upgrade:check`. It compares the Fluid files below one or more
project override folders with the files the installed academic extension ships,
and reports every file that no longer matches one.

```bash
vendor/bin/typo3 academic:upgrade:check academic_persons_edit \
    --override-path=EXT:my_site/Resources/Private/Extensions/AcademicPersonsEdit/
```

```text
EXT:my_site/Resources/Private/Extensions/AcademicPersonsEdit/
  compared with EXT:academic_persons_edit/Resources/Private/
  x missing-upstream  Templates/Profile/Show.html
  = identical         Partials/Profile/Image.html
  ! case-mismatch     Pages/Academicprogram.html -> Pages/AcademicProgram.html

2 problems and 1 notice in 1 override folder.
```

Three findings are reported:

| Finding | Meaning | Exit status |
| --- | --- | --- |
| `missing-upstream` | The extension ships no file at that relative path, not even one differing in case. Fluid never resolves the override. | problem |
| `case-mismatch` | The extension ships the file under a name that differs only in case. Such an override resolves on a case insensitive file system and is dead on the Linux server next to it. | problem |
| `identical` | The override is a byte identical copy. It renders, and it freezes the markup of that one file at the version it was taken from. | notice |

A changed copy of a file the extension still ships is not reported: it is a
deliberate override that works.

The command exits with `1` when at least one problem is reported, with
`2` on invalid input, and with `0` otherwise - a notice alone does
not fail a pipeline. It only reads; it changes no file.

## Naming the folders {#feature-upgrade-check-command-options}

-   **extension**

    -   *Type:* string
    -   *Required:* true

    The extension key of the academic extension the overrides belong to, for
    example `academic_persons_edit`.

-   **--override-path**

    -   *Type:* string

    A folder holding the project overrides, as an `EXT:` path or an
    absolute path. May be given more than once. It is compared with
    `EXT:<extension>/Resources/Private/`.

-   **--upstream-path**

    -   *Type:* string

    The folder the override folders are compared with, when the override folder
    mirrors a single one rather than `Resources/Private/`:

    ```bash
    vendor/bin/typo3 academic:upgrade:check academic_persons \
        --override-path=EXT:my_site/Resources/Private/Partials/Academic/ \
        --upstream-path=EXT:academic_persons/Resources/Private/Partials/
    ```

-   **--site**

    -   *Type:* string

    Take the override folders from the TypoScript of that site instead of from
    the command line, by its site identifier. It may be combined with
    `--override-path`.

## Taking the folders from a site {#feature-upgrade-check-command-site}

With `--site` the command builds a frontend environment for the site's
root page and reads the view root paths the site's TypoScript configures for the
extension's plugins - `plugin.tx_academicpersons.view.templateRootPaths`,
`partialRootPaths` and `layoutRootPaths`. Each folder is
compared with the upstream folder of its own kind, so `--upstream-path` is
not needed there.

```bash
vendor/bin/typo3 academic:upgrade:check academic_persons --site=main
```

A root path is only treated as a project override when it lies outside the
checked extension, outside every extension it depends on and outside the TYPO3
system extensions. The partial root paths of the academic plugins name the
shared partials of `EXT:academic_base`, and those of
`EXT:academic_persons_edit` name the partials of
`EXT:fluid_styled_content`; neither is a project override, and reporting
them would bury the findings that matter.

The command exits with `2` and names the site when the site does not
exist, when its frontend environment cannot be built, when its TypoScript
configures no view root path for the extension at all, or when a root path names
a folder that does not exist - the last one together with the TypoScript path
that named it.

For the `page.10` root paths of a site the command is deliberately
not used: they are shared with the site's theme, so every theme template would
be reported as `missing-upstream`. Point `--override-path` at the
page template folder instead.

## Impact {#impact}

Integrators get a check they can run before and after an upgrade of the academic
extensions, and in continuous integration. Nothing in TYPO3 reports a template
override that no longer resolves, so before this command such an override was
found by noticing that the frontend no longer looks the way the project
configured it.

`EXT:academic_base` requires `fgtclb/environment-state-manager` for the
`--site` mode and declares it in `composer.json` and in
`ext_emconf.php`. The dependency came with 2.4.0, for the internal
environment subsystem that 3.0 removed, and 3.0 raises it to version 2, see
[Important: fgtclb/environment-state-manager 2 is required](https://docs.typo3.org/permalink/fgtclb/academic-base:important-environment-state-manager-2@main). Composer managed installations
update the package on their own. Classic installations update the
`environment_state_manager` extension to 2.x first.