There are no working instructions to update the database

[nomonkeynodeal]

I tried updating, following the instructions to delete /db and db.version, adding checkpoint-sync-url. This resulted in:

java.util.concurrent.CompletionException: java.lang.NullPointerException: Cannot invoke "tech.pegasys.teku.storage.server.metadata.V6DatabaseMetadata$SingleDBMetadata.getConfiguration()" because the return value of "tech.pegasys.teku.storage.server.metadata.V6DatabaseMetadata.getSingleDbConfiguration()" is null

Perplexity is telling me the instructions are wrong and I have to resync? What is the actual way to update?

It specifically says that it requires the checkpoint-sync-url or initial-state or it won't create the new database.

WRONG ORDER (what instructions told you):

1. Delete db/ + db.version
2. Add checkpoint-sync-url
3. Restart → CRASH (null metadata during DB creation)

CORRECT ORDER:

1. Delete db/ + db.version
2. Restart WITHOUT checkpoint-sync-url → Teku would error "missing checkpoint"
3. Teku needs checkpoint FIRST for new DB

[lucassaldanha]

Could you share the commands you used to perform these operations? The instructions you claim to be wrong are the correct instructions so I am not sure what went wrong in your situation.

To be clear, ther first thing you do is stop your node. After that, delete db directory (whole directory, not just its contents), delete db.version, and add the checkpoint-sync-url options, with your chosen provider. After that you start your onde again and everything should just work.

I'd be happy to understand what went wrong in your case so we can help others in the same situation, but the instructions are correct and we have used them many times :)

[nomonkeynodeal]

I should have mentioned this is actually a Windows 10 device. I just removed the folder and file, added checkpoint-sync-url to the config, and updated Teku. I was able to restore the files and just use the old db for now.

[rolfyone]

In case anyone else finds this

• shutdown teku
• delete db folder and db.version
• make sure you dont have --Xdata-storage-create-db-version set to leveldb2, or change it to be 6 in your configuration options
• start teku (on 26.2.0 or above)
• check db.version file now says 6 after teku has started

[nomonkeynodeal]

In case anyone else finds this

* shutdown teku

* delete db folder and db.version

* make sure you dont have `--Xdata-storage-create-db-version` set to leveldb2, or change it to be `6` in your configuration options

* start teku (on 26.2.0 or above)

* check db.version file now says `6` after teku has started

This is exactly what I did the first time and again just now.

2026-03-03 11:38:16.916-0600 | main | FATAL | BeaconNodeCommand | Teku failed to start
java.util.concurrent.CompletionException: java.lang.NullPointerException: Cannot invoke "tech.pegasys.teku.storage.server.metadata.V6DatabaseMetadata$SingleDBMetadata.getConfiguration()" because the return value of "tech.pegasys.teku.storage.server.metadata.V6DatabaseMetadata.getSingleDbConfiguration()" is null
at java.base/java.util.concurrent.CompletableFuture.encodeThrowable(CompletableFuture.java:332)
at java.base/java.util.concurrent.CompletableFuture.uniComposeStage(CompletableFuture.java:1177)
at java.base/java.util.concurrent.CompletableFuture.thenCompose(CompletableFuture.java:2341)
at tech.pegasys.teku.infrastructure.async.SafeFuture.thenCompose(SafeFuture.java:684)
at tech.pegasys.teku.services.chainstorage.StorageService.doStart(StorageService.java:254)
at tech.pegasys.teku.service.serviceutils.Service.start(Service.java:36)
at tech.pegasys.teku.services.ServiceController.lambda$doStart$0(ServiceController.java:29)
at java.base/java.util.concurrent.CompletableFuture.uniComposeStage(CompletableFuture.java:1187)
at java.base/java.util.concurrent.CompletableFuture.thenCompose(CompletableFuture.java:2341)
at tech.pegasys.teku.infrastructure.async.SafeFuture.thenCompose(SafeFuture.java:684)
at tech.pegasys.teku.services.ServiceController.doStart(ServiceController.java:29)
at tech.pegasys.teku.service.serviceutils.Service.start(Service.java:36)
at tech.pegasys.teku.AbstractNode.start(AbstractNode.java:214)
at tech.pegasys.teku.Teku.start(Teku.java:81)
at tech.pegasys.teku.Teku.lambda$startFromCLIArgs$2(Teku.java:89)
at tech.pegasys.teku.cli.BeaconNodeCommand.call(BeaconNodeCommand.java:348)
at tech.pegasys.teku.cli.BeaconNodeCommand.call(BeaconNodeCommand.java:78)
at picocli.CommandLine.executeUserObject(CommandLine.java:2031)
at picocli.CommandLine.access$1500(CommandLine.java:148)
at picocli.CommandLine$RunLast.executeUserObjectOfLastSubcommandWithSameParent(CommandLine.java:2469)
at picocli.CommandLine$RunLast.handle(CommandLine.java:2461)
at picocli.CommandLine$RunLast.handle(CommandLine.java:2423)
at picocli.CommandLine$AbstractParseResultHandler.execute(CommandLine.java:2277)
at picocli.CommandLine$RunLast.execute(CommandLine.java:2425)
at picocli.CommandLine.execute(CommandLine.java:2174)
at tech.pegasys.teku.cli.BeaconNodeCommand.parse(BeaconNodeCommand.java:280)
at tech.pegasys.teku.Teku.start(Teku.java:62)
at tech.pegasys.teku.Teku.startFromCLIArgs(Teku.java:89)
at tech.pegasys.teku.Teku.main(Teku.java:39)
Caused by: java.lang.NullPointerException: Cannot invoke "tech.pegasys.teku.storage.server.metadata.V6DatabaseMetadata$SingleDBMetadata.getConfiguration()" because the return value of "tech.pegasys.teku.storage.server.metadata.V6DatabaseMetadata.getSingleDbConfiguration()" is null
at tech.pegasys.teku.storage.server.VersionedDatabaseFactory.initV6Configuration(VersionedDatabaseFactory.java:318)
at tech.pegasys.teku.storage.server.VersionedDatabaseFactory.createV6Database(VersionedDatabaseFactory.java:231)
at tech.pegasys.teku.storage.server.VersionedDatabaseFactory.createDatabase(VersionedDatabaseFactory.java:137)
at tech.pegasys.teku.services.chainstorage.StorageService.lambda$doStart$1(StorageService.java:114)
at tech.pegasys.teku.infrastructure.async.SafeFuture.fromRunnable(SafeFuture.java:157)
at tech.pegasys.teku.services.chainstorage.StorageService.doStart(StorageService.java:92)
... 24 more

[rolfyone]

can you please cat db.version, and also now you'd need 26.3 at a minimum because there was an issue with state size.

[nomonkeynodeal]

db.version contains "5". I'm using 26.3.

I have a feeling you're going to tell me it's supposed to be 6 or whatever it's supposed to be after I update the database, but the update did not work, so I am not using the updated database.

[rolfyone]

ok so version 5 is unusual, i'll have a look. maybe remove Xdata-storage-create-db-version=5 from your settings and use v.6 which is the one thats heavily used...

[nomonkeynodeal]

Are you suggesting that I have this setting and should change it? (I don't.) Or that if I don't have it I should add it?

[rolfyone]

if its set on 5 the only way i could see that if its a database from .... maybe 2021, or theres an explicit setting to say use that version?

[nomonkeynodeal]

There's no database setting in the config. Should I just resync? How do I do that?

[rolfyone]

theres options / thoughts below so read the whole comment before making changes...

if you know where your beacon folder is, theres a db folder, and a db.version file, and you can stop teku, then remove those 2... rm -rf db db.version in that beacon folder
could alternatively just mv db db.old and delete the version file, or manually edit it to 6... once its started could definitely delete db.old...

you'll want to make sure you have either --initial-state or --checkpoint-sync-url set to something valid, and then startup and your db will start fresh...

after you startup, you should see a new db folder, and the db.version file should be 6. if its not that, its potentially that you have a database version set in a service file or something - this is harder to describe, often /etc/systemd/system/teku file would have settings in there, as well as ... sometimes /etc/teku/teku.yml, if you're in docker this is all not really how it's set out...

[nomonkeynodeal]

I am running in Windows 10. The source of config settings on my system is the teku.yaml. There are only a few settings, mostly IP related. I already tried removing the db.version and db folder several times, following the instructions. That is when I get the error I posted above. I can resync my data if necessary, but I think that might not even solve my problem.

[rolfyone]

I can't replicate the error, I'll see if the person using windows on our team can take a look - sorry for the delay.