Restore a Nextcloud Docker Backup: Fix "password authentication failed for user oc_admin"

A Nextcloud Docker backup is the volume and a database dump, taken in maintenance mode. On the official Postgres setup, though, Nextcloud signs in to its database with its own account, oc_admin, which pg_dump does not carry, so a restored server fails with "password authentication failed". Recreate that account from config.php to rescue it, and back up the database accounts too so the next restore just works.

Watch on YouTube · published Nov 21, 2026 · 6:27

A Nextcloud backup in Docker is two things: the Nextcloud volume and a dump of the database, taken while the server is in maintenance mode. If your database is Postgres and you installed with the official image, there is a catch. Nextcloud signs in to Postgres with an account of its own, oc_admin, and pg_dump does not copy accounts. Restore onto a new server and you get Internal Server Error, with password authentication failed for user "oc_admin" in the log. The password is in config.php, so you can recreate the account. Better still, back the account up as well.

We tested all of this in November 2026 on Nextcloud 35.0.1 (nextcloud:35.0.1-apache) with postgres:16-alpine. We backed the server up, deleted both containers and both volumes, and restored it from the backup. A starred file and a public share link (which exist only in the database) came back, and the old link still worked. For what a backup needs according to Nextcloud's manual, and why the old Backup app is not the answer, see How to back up Nextcloud.

How do I back up Nextcloud in Docker?

Replace nextcloud and db with the names of your own containers and volume:

docker exec -u www-data nextcloud php occ maintenance:mode --on
docker exec db pg_dump -U nextcloud nextcloud > nextcloud-db.sql
docker exec db pg_dumpall -U nextcloud --roles-only > nextcloud-roles.sql
docker run --rm -v nextcloud:/from:ro -v /backup:/to alpine \
  tar cf /to/nextcloud-volume.tar -C /from .
docker exec -u www-data nextcloud php occ maintenance:mode --off

The volume holds the config folder, the apps and the data folder (unless you mounted data somewhere else, in which case copy that too). The third line is the one most guides leave out. Keep the files off the server: on another drive or another machine. A copy on the same disk goes when that disk goes.

Why does my restored Nextcloud say "password authentication failed for user oc_admin"?

The official Docker setup gives Nextcloud the Postgres admin account (POSTGRES_USER) to install with. Nextcloud's installer (lib/private/Setup/PostgreSQL.php) does not keep using it: when that login can create accounts, it creates oc_admin with a newly generated password and writes both into config.php. Accounts belong to the database server, not to one database, and pg_dump copies one database. A new Postgres container only has the account from your compose file, so the restored Nextcloud cannot sign in.

Check yours: if dbuser in config.php is not the user in your compose file, this applies to you. With MariaDB or MySQL and the usual non-root MYSQL_USER, the installer keeps that user and the problem usually does not arise, but the same check tells you.

How do I fix it?

docker exec nextcloud grep -E "dbuser|dbpassword" config/config.php
docker exec db psql -U nextcloud -d template1 \
  -c "CREATE USER oc_admin WITH PASSWORD '<dbpassword>' CREATEDB;"
docker exec db psql -U nextcloud -d template1 -c 'DROP DATABASE "nextcloud";'
docker exec db psql -U nextcloud -d template1 -c 'CREATE DATABASE "nextcloud";'
docker exec -i db psql -U nextcloud -d nextcloud < nextcloud-db.sql
docker exec -u www-data nextcloud php occ maintenance:mode --off

Load the dump again after creating the account, so its tables belong to oc_admin rather than to whoever loaded them first. The last line matters too: the backup was taken in maintenance mode, so config.php comes back with maintenance switched on.

How do I restore with the accounts backed up?

docker volume create nextcloud
docker run --rm -v nextcloud:/to -v /backup:/from alpine \
  tar xf /from/nextcloud-volume.tar -C /to
# start the db and nextcloud containers as before, then:
docker exec -i db psql -U nextcloud -d template1 < nextcloud-roles.sql
docker exec -i db psql -U nextcloud -d nextcloud < nextcloud-db.sql
docker exec -u www-data nextcloud php occ maintenance:mode --off

The roles file prints one harmless error, role "nextcloud" already exists, because the new container made that account itself.

Anything else after a restore?

If the backup is older than what your desktop clients have synced, Nextcloud's manual suggests occ maintenance:data-fingerprint, so clients can put back files the server lost. It warns that this "can cause conflict dialogues and difficulties deleting files on the client". If you use Nextcloud All-in-One, it has its own built-in BorgBackup instead of the steps above.

And restore once, on purpose, before you need to. This page exists because the manual's steps, followed exactly, produced a server that would not start.

Full video transcript

1
00:00:00,000 --> 00:00:02,652
A Nextcloud backup in
Docker is two things.

2
00:00:02,692 --> 00:00:06,783
The volume, and a dump of the
database, taken in maintenance mode.

3
00:00:06,823 --> 00:00:08,786
But on the usual Postgres setup,

4
00:00:08,826 --> 00:00:13,230
the account Nextcloud signs in to
its database with isn't in that dump.

5
00:00:13,270 --> 00:00:17,987
So I'll back up this server, delete it
completely, and restore it. It fails.

6
00:00:18,027 --> 00:00:22,534
Then I'll show you why, how to rescue
it, and the backup that avoids it.

7
00:00:22,934 --> 00:00:24,946
This is Nextcloud thirty five.

8
00:00:24,986 --> 00:00:28,366
It runs in Docker, on a
Linux server I run myself,

9
00:00:28,406 --> 00:00:32,402
with its Postgres database in
a second container beside it.

10
00:00:32,442 --> 00:00:34,768
This is the admin's Family folder.

11
00:00:36,001 --> 00:00:40,558
Two files. One is starred. The
other is shared with a public link.

12
00:00:40,598 --> 00:00:42,856
The files themselves sit on disk.

13
00:00:42,896 --> 00:00:48,010
But the star and the link only exist
in the database. Keep an eye on them.

14
00:00:48,050 --> 00:00:51,671
If a restore loses the
database, it loses those too.

15
00:00:52,957 --> 00:00:56,150
This is that share link, the
page anyone who has it sees.

16
00:00:56,190 --> 00:01:00,727
After I delete this server and restore
it, the very same link should still work.

17
00:01:02,704 --> 00:01:03,611
Now the backup.

18
00:01:03,651 --> 00:01:07,272
Nextcloud's manual says to turn
on maintenance mode first,

19
00:01:07,312 --> 00:01:09,418
so nothing changes while you copy.

20
00:01:09,458 --> 00:01:12,322
Then, in Docker, there
are two things to copy.

21
00:01:12,362 --> 00:01:15,605
The database, which you dump
to a file with pg_dump.

22
00:01:15,645 --> 00:01:20,340
And the Nextcloud volume, which holds
the config, the apps, and your files.

23
00:01:20,380 --> 00:01:22,423
I'll put both in a backup folder.

24
00:01:22,463 --> 00:01:26,148
On this server, that folder
stands in for a separate drive.

25
00:01:26,188 --> 00:01:29,597
On yours, keep it on another
disk, or another machine.

26
00:01:32,121 --> 00:01:35,064
Maintenance mode is on. Reload the page.

27
00:01:36,577 --> 00:01:40,368
This Nextcloud instance is
currently in maintenance mode.

28
00:01:40,408 --> 00:01:43,191
Every visitor gets this page, me included.

29
00:01:43,231 --> 00:01:47,358
So no file and no database row
can change while the copy runs.

30
00:01:47,398 --> 00:01:51,093
While this page is up, I run
the dump, and the archive.

31
00:01:53,589 --> 00:01:56,789
Both are done, and
maintenance mode is off again.

32
00:01:56,829 --> 00:02:01,286
The server is back to normal, and
the backup folder holds two files.

33
00:02:01,326 --> 00:02:04,104
The database dump, and the volume archive.

34
00:02:05,312 --> 00:02:07,757
Now the disaster. Say the disk dies.

35
00:02:07,797 --> 00:02:13,210
Here, I remove both containers, and both
volumes, the app's and the database's.

36
00:02:13,250 --> 00:02:17,806
Everything the server had is gone.
Only the backup folder is left.

37
00:02:20,293 --> 00:02:21,354
Reload.

38
00:02:22,686 --> 00:02:27,201
This site can't be reached. There's
no Nextcloud here at all now.

39
00:02:28,426 --> 00:02:33,754
To restore, go in reverse. Make a new, empty
volume, and unpack the archive into it.

40
00:02:33,794 --> 00:02:37,716
Start a fresh Postgres container,
and the Nextcloud container,

41
00:02:37,756 --> 00:02:39,825
with the same settings as before.

42
00:02:39,865 --> 00:02:42,485
Then load the dump into the new database.

43
00:02:44,990 --> 00:02:47,758
Nextcloud's manual has a restore page too.

44
00:02:48,062 --> 00:02:52,356
You must have the database, data
directory, and configuration files.

45
00:02:52,396 --> 00:02:57,009
You cannot complete restoration without
all three. And we have all three.

46
00:02:57,049 --> 00:03:01,510
The volume holds the data and the
config. The dump holds the database.

47
00:03:03,977 --> 00:03:08,604
The archive is unpacked, and the
dump is loaded. Reload Nextcloud.

48
00:03:09,817 --> 00:03:14,921
Internal Server Error. Everything was in
the backup, and it still won't start.

49
00:03:14,961 --> 00:03:18,126
The page says the details
are in the server log.

50
00:03:20,579 --> 00:03:25,752
Here's the line from that log. Password
authentication failed, for user oc_admin.

51
00:03:25,792 --> 00:03:29,678
That's the account Nextcloud
uses to sign in to its database.

52
00:03:29,718 --> 00:03:33,000
And this new database server
has never heard of it.

53
00:03:34,257 --> 00:03:36,678
So where did that account come from?

54
00:03:36,718 --> 00:03:42,079
The official Docker setup hands Nextcloud
the Postgres admin account to install

55
00:03:42,119 --> 00:03:42,421
with.

56
00:03:42,461 --> 00:03:44,609
Nextcloud doesn't keep using it.

57
00:03:44,649 --> 00:03:48,916
It makes its own account, oc_admin,
with a new random password,

58
00:03:48,956 --> 00:03:51,104
and writes both into config.php.

59
00:03:51,144 --> 00:03:55,479
That account lives in the database
server, beside your database.

60
00:03:55,519 --> 00:03:59,581
And pg_dump copies the database,
not the accounts around it.

61
00:03:59,621 --> 00:04:02,285
So the account was never in the backup.

62
00:04:03,620 --> 00:04:06,889
The good news is that the
password came back too.

63
00:04:06,929 --> 00:04:10,603
It's in config.php, inside
the volume we just restored.

64
00:04:10,643 --> 00:04:14,317
So read the database user
and password from config.php.

65
00:04:14,357 --> 00:04:18,706
Create that account in the new
Postgres, with that same password.

66
00:04:18,746 --> 00:04:21,880
Then drop the database
and load the dump again,

67
00:04:21,920 --> 00:04:24,621
so its tables belong to the right owner.

68
00:04:27,125 --> 00:04:29,193
I've run those. Reload.

69
00:04:31,683 --> 00:04:34,841
Maintenance mode. This
time it isn't an error.

70
00:04:34,881 --> 00:04:37,691
The backup was taken in maintenance mode,

71
00:04:37,731 --> 00:04:40,750
so config.php came back
with it switched on.

72
00:04:40,790 --> 00:04:42,875
One more command turns it off.

73
00:04:45,339 --> 00:04:46,941
That was the last command.

74
00:04:46,981 --> 00:04:50,161
Reload once more, and go
back to the Family folder,

75
00:04:50,201 --> 00:04:53,232
where the starred file
and the shared link were.

76
00:04:53,605 --> 00:04:56,381
The server is back. And
I'm still signed in.

77
00:04:56,421 --> 00:05:01,094
My login is stored in the database
too, so it came back with the restore.

78
00:05:02,337 --> 00:05:05,795
Both files are here. The important
documents are still starred.

79
00:05:05,835 --> 00:05:10,237
And the guest list still shows it's shared.
The files came back from the volume.

80
00:05:10,277 --> 00:05:13,053
The star and the link came
back from the database.

81
00:05:14,307 --> 00:05:15,768
Now the share link.

82
00:05:20,618 --> 00:05:25,086
It's the same link as before the server
was deleted, and it still works.

83
00:05:25,126 --> 00:05:28,445
Whoever you sent it to never
knows anything happened.

84
00:05:29,689 --> 00:05:34,199
So here's the better backup. Add one
more file: the database accounts.

85
00:05:34,239 --> 00:05:38,034
pg_dumpall, with roles only,
saves them, password included.

86
00:05:38,074 --> 00:05:43,429
On restore, load that file first, and the
account is there before the dump arrives.

87
00:05:43,469 --> 00:05:46,939
No rescue needed. I've tested
that on this server too.

88
00:05:46,979 --> 00:05:51,749
Keep all three files off the server,
on another drive, or another machine.

89
00:05:51,789 --> 00:05:55,819
And restore them once, on purpose,
before the day you need to.

90
00:05:57,781 --> 00:06:02,062
So. Back up the volume and a
database dump, in maintenance mode.

91
00:06:02,102 --> 00:06:06,990
If a restore says password authentication
failed, the account is missing,

92
00:06:07,030 --> 00:06:09,285
and its password is in config.php.

93
00:06:09,325 --> 00:06:13,471
Create it, load the dump again,
and turn maintenance mode off.

94
00:06:13,511 --> 00:06:16,509
Next time, back up the
database accounts too.

95
00:06:16,549 --> 00:06:21,167
Keep it all on another drive, and
test a restore before you need one.

96
00:06:21,207 --> 00:06:24,043
Every command is on the page linked below.


Related reading