Upgrade stuck: commonsubtotal.class.php not found

During an upgrade to 22, 23 or 24, the wizard stops on a missing subtotals file. It is not an external module: the copy of the files is incomplete.

Versions concerned
Upgrade from version 21 or older to 22, 23 or 24 · tested from 21.0.4 to 24.0.1
What was checked
Tested on 4 October 2026: real upgrade 21.0.424.0.1 with the wizard, subtotals/ folder removed; message obtained at the data migration step, then migration finished once the folder was put back. Line number checked in 22.0.5 (53), 23.0.4 (54) and 24.0.1 (55). Presence of the folder checked in the official code: absent in 20.0.4 and 21.0.4, present from 22.0.0 to 24.0.2.

You are upgrading Dolibarr. At the data migration step, the wizard stops on this message:

Warning: require_once(../subtotals/class/commonsubtotal.class.php): Failed to open stream:
No such file or directory in …/compta/facture/class/facture.class.php on line 55

It is followed by a fatal error “Failed opening required”. The line number is 53 in version 22, 54 in 23 and 55 in 24. Under PHP 7, the message starts with “failed”, in lower case.

If your server does not display errors, you only see a blank page (error 500): the same message is then in the PHP error log.

It is not an external module

The first thought is an old subtotals module. It is not one: the subtotals/ folder has been part of Dolibarr itself since version 22. External modules, for their part, are installed in custom/.

So the message says two things:

  • facture.class.php is already the one from the new version. It is the file asking for it.
  • The subtotals/ folder did not reach the server.

The ../ at the start of the path is normal: during the upgrade, Dolibarr works from the install/ folder, where the root is defined as “the folder above”.

The cause: an incomplete copy of the files

The existing files were replaced, but the subtotals/ folder, new in version 22, was not created. This happens for example after an interrupted transfer, or if only the modified files were copied. If one folder is missing, other files may be missing too.

The solution

  1. Check on the server whether the subtotals/ folder exists at the root of Dolibarr, next to compta/, comm/ and install/.
  2. If it is missing, copy all the content of the htdocs folder of the target version’s archive over your installation, without deleting your conf/conf.php or the custom/ folder.
  3. Run the upgrade wizard again (/install/).

Do not copy only subtotals/: if one folder is missing, the whole copy is doubtful.

How this was verified

  • Real upgrade of a 21.0.4 instance to 24.0.1 with the wizard, subtotals/ folder removed: the structure step passes, the data migration step stops on this message, line 55 included (blank page, message in the PHP log). Folder put back: “Migration finished”.
  • Same message in 22.0.5 (line 53) and in 23.0.4 (line 54). “failed” in lower case under PHP 7.4.
  • In the official code, the subtotals/ folder is absent from versions 20.0.4 and 21.0.4, and present from 22.0.0 to 24.0.2.

The full procedure, with the backup and the rollback, is described in Dolibarr upgrade: checklist and upgrade path. If the upgrade goes through but a page stays blank afterwards, see Dolibarr error 500 or blank page.

If the upgrade is still stuck

If the folder is there and the wizard still stops, the €90 diagnosis is about looking at your installation with you for one hour, then giving you in writing the cause and what the fix would cost.

Dolibarrupgradesubtotalscommonsubtotalrequire_onceFailed to open stream