jsondb, upgradetool.jar — difference between a missing file and a file with content `{}`

[dilyanpalauzov]

OpenHAB creates /var/lib/openhab/jsondb/org.openhab.core.items.Item.json and /var/lib/openhab/jsondb/org.openhab.core.thing.link.ItemChannelLink.json, only when an item and a link to it are created over MainUI. If this linked item is later removed, the mentioned files contain just {}. It turns out, there is a difference between a missing file in jsondb and a file with content {}:

During OpenHAB upgrade to 5.1 the system logs:

[openHAB] Running JSON Database upgrade tool (${OPENHAB_RUNTIME}/bin/upgradetool.jar).
[main] INFO org.openhab.core.tools.UpgradeTool - Executing itemCopyUnitToMetadata: Copy item unit from state description to metadata
[main] INFO org.openhab.core.tools.internal.ItemUnitToMetadataUpgrader - Copying item unit from state description to metadata in database '/var/lib/openhab/jsondb/org.openhab.core.items.Item.json'
[main] ERROR org.openhab.core.tools.internal.ItemUnitToMetadataUpgrader - Cannot access item database '/var/lib/openhab/jsondb/org.openhab.core.items.Item.json', check path and access rights.
[main] INFO org.openhab.core.tools.UpgradeTool - Executing linkUpgradeJSProfile: Upgrade JS profile configuration to new format
[main] INFO org.openhab.core.tools.internal.JSProfileUpgrader - Upgrading JS profile configuration in database '/var/lib/openhab/jsondb/org.openhab.core.thing.link.ItemChannelLink.json'
[main] ERROR org.openhab.core.tools.internal.JSProfileUpgrader - Cannot access link database '/var/lib/openhab/jsondb/org.openhab.core.thing.link.ItemChannelLink.json', check path and access rights.
[main] INFO org.openhab.core.tools.UpgradeTool - Executing linkUpgradeScriptProfile: Upgrade script profile configuration toHandlerScript to commandFromItemScript
[main] INFO org.openhab.core.tools.internal.ScriptProfileUpgrader - Upgrading script profile configuration in database '/var/lib/openhab/jsondb/org.openhab.core.thing.link.ItemChannelLink.json'
[main] ERROR org.openhab.core.tools.internal.ScriptProfileUpgrader - Cannot access link database '/var/lib/openhab/jsondb/org.openhab.core.thing.link.ItemChannelLink.json', check path and access rights.
[main] INFO org.openhab.core.tools.UpgradeTool - Already executed 'yamlTagsListToMap' on 2025-09-08T10:31:54.968080262+01:00[Europe/London]. Use '--force' to execute it again.
[openHAB] JSON Database upgrade completed.

So OpenHAB distinguishes between a missing file in jsondb and a file with content {}. Under this conditions either OpenHAB should unconditionally create org.openhab.core.items.Item.json and org.openhab.core.thing.link.ItemChannelLink.json with content {}, or upgradetool.jar should not log a message, when the files are missing.

[rkoshak]

There actually is a difference between those two cases.

Lack of the file means either there has never been that file or it's been removed inadvertently. To catch this latter case, if the file doesn't exist, OH will look to see if there is a file in backup and if so it uses that backup file.

A file containing { } means that there is deliberately no Items defined in the JSONDB.

Therefore, there are actually three conditions:

1. file contains { }
2. file doesn't exist but a backup exists
3. neither file nor backup exists

I filed an issue a few years ago against OH silently just using the backup file in case 2, but it never really went anywhere.

Because of the behavior OH does for 2, I don't think it's as simple as upgradeTool not logging the error message nor would it be correct to just create the file with { } as its contents.

Given the current behavior of OH, I think what upgradeTool should do is:

1. nothing different, the file exists
2. restore the most recent backup of the file and emit a warning or info level log to make it clear that this was done prior to attempting to upgrade that file, then run the upgrade task
3. do nothing except maybe emit a warning or info level log to indicate the file doesn't exist but the file not existing is not an error.

[dilyanpalauzov]

To express myself in different words, there should be a no difference between a fresh OpenHAB installation, and an OpenHAB installation, where an item is first created over MainUI and then deleted over MainUI. But there is a difference: if no item is created, the file /var/lib/openhab/jsondb/org.openhab.core.items.Item.json does not exist; if the item is created and then deleted, the file /var/lib/openhab/jsondb/org.openhab.core.items.Item.json exists.

[rkoshak]

But there is a difference if the file doesn't exist, but a backup of the file does exist. Therefore, you cannot treat all three cases exactly the same or else things break.

There shouldn't be an error if the file doesn't exist and there is no backup file, I agree.

But if there is no file and there is a backup, creating a file with { } is a breaking change. Those users will basically lose all their Items (eg) with no explanation for why.

If there is no file and there is a backup, simply silently ignoring that the file doesn't exist means OH will start up using the backup file which has not been run through upgradeTool. This could result in a broken config. I think this is how it works now anyway and that should be fixed. Hence my suggestion above.