Overview

Restore a MongoDB Database Tools archive compressed with gzip into an existing MongoDB Docker container. The example backup filename is mongobackup-2025-11-03-1152.gz; it is a sample, not evidence of the file’s actual format. This runbook assumes the backup was produced with archive + gzip options:

mongodump --archive=mongobackup.gz --gzip

Replace every angle-bracket placeholder before running a command. Commands labelled Host run on the Docker host; commands labelled Container run inside the MongoDB container. localhost is the local connection target, not an infrastructure hostname.

Jump to: Authenticated restore · Authentication error · Host restore · Verification · Backup formats · Troubleshooting · Command reference · Recommended procedure.

Prerequisites

  • Access to the intended Docker host and MongoDB container, plus permission to execute commands there.
  • A readable backup and enough free space for the copied archive, restored data, and rebuilt indexes. Keep the original backup unchanged.
  • MongoDB Database Tools where you run the restore; mongosh for verification. Do not assume the container image includes either.
  • Credentials authorized to restore the intended namespaces. A valid login does not automatically grant restore privileges.
  • A compatible source/target MongoDB version and Database Tools version. Check MongoDB’s compatibility guidance before restoring across versions.
  • A reviewed target and scope. Prefer an isolated test instance first. Coordinate application writes and take a recovery backup before changing an existing database.

These examples assume a local standalone endpoint on port 27017 without TLS. Adapt connection and TLS options to the target deployment; do not disable authentication or certificate verification to make a restore work. See the mongorestore reference for compatibility and required-access details.

Identify the MongoDB Docker Container

docker ps
docker exec '<mongo-container>' mongorestore --version
docker exec '<mongo-container>' mongosh --version

Use the intended container’s name or ID from the local output. Keep those identifiers out of shared notes. Docker access is separate from MongoDB authentication.

Copy the Backup into the Container

docker cp mongobackup-2025-11-03-1152.gz '<mongo-container>:/tmp/'
docker exec -it '<mongo-container>' bash

If bash is unavailable, use the image’s shell:

docker exec -it '<mongo-container>' sh

The restore process must be able to read the copied file. From here, the following container commands connect to localhost:27017, which normally reaches MongoDB in that same container. A different container has a different localhost; a separate tools container needs an explicitly configured network target.

Restore Without Authentication

mongorestore \
  --gzip \
  --archive=/tmp/mongobackup-2025-11-03-1152.gz

Use this only when the intended server already runs without authentication. Do not turn authentication off to bypass an error. With no namespace filter, the restore can process all namespaces stored in the archive. It is not limited to one application database.

Restore When MongoDB Authentication Is Enabled

Recommended interactive form: supply the username and authentication database, but omit the password so the tool prompts for it. Run from an interactive terminal.

mongorestore \
  --gzip \
  --archive=/tmp/mongobackup-2025-11-03-1152.gz \
  --username '<mongo-user>' \
  --authenticationDatabase admin

The explicit-password equivalent is shown below for syntax reference. Replacing the placeholder with a real password can expose it through shell history or process arguments; prefer the prompt above.

mongorestore \
  --gzip \
  --archive=/tmp/mongobackup-2025-11-03-1152.gz \
  --username '<mongo-user>' \
  --password '<mongo-password>' \
  --authenticationDatabase admin

URI-based equivalent:

mongorestore \
  --gzip \
  --archive=/tmp/mongobackup-2025-11-03-1152.gz \
  --uri='mongodb://<mongo-user>:<mongo-password>@localhost:27017/?authSource=admin'

Percent-encode reserved characters in URI usernames and passwords; shell quoting does not perform URI encoding. To use a URI with a prompt, omit the password portion:

mongorestore \
  --gzip \
  --archive=/tmp/mongobackup-2025-11-03-1152.gz \
  --uri='mongodb://<mongo-user>@localhost:27017/?authSource=admin'
  • --gzip: decompress the gzip-compressed dump input.
  • --archive: read the single Database Tools archive file, rather than a directory of BSON files.
  • --username: identify the MongoDB user used for the restore.
  • --password: provide the user’s password; omitting it with a username allows an interactive prompt.
  • --authenticationDatabase admin: look up the user in admin. Use the database where the user was actually created.
  • authSource=admin: URI equivalent of the authentication-database setting; it does not select the database being restored.

The archive determines destination namespaces unless filters or remapping options change them. For one database, add a quoted namespace filter to the restore command:

mongorestore \
  --gzip \
  --archive=/tmp/mongobackup-2025-11-03-1152.gz \
  --username '<mongo-user>' \
  --authenticationDatabase admin \
  --nsInclude='<database-name>.*'

MongoDB’s restore examples cover compressed archives and interactive credential handling.

Understanding the Authentication Error

Failed: error getting auth version of server: (Unauthorized) Command getParameter requires authentication
0 document(s) restored successfully. 0 document(s) failed to restore.

The tool reached MongoDB, but the connection was not authenticated sufficiently to execute the required command. This is not a Docker copy failure or a gzip decoding error. Retry with the correct user, password, and authentication database. If authentication succeeds but later operations are denied, check the user’s restore privileges for the requested scope.

“0 failed” does not make this run successful: it failed before document restoration began. Read the preceding error and check the process exit status immediately after the command:

echo $?

Restore Directly from the Docker Host

Copying is optional if Database Tools are installed on the host and the container’s MongoDB port is published. Check the mapping:

docker port '<mongo-container>' 27017/tcp

The next command assumes container port 27017 maps to host port 27017. Adjust the URI if the host port differs. Here localhost means the Docker host, not the container. An image’s EXPOSE metadata alone does not publish a port.

mongorestore \
  --gzip \
  --archive=./mongobackup-2025-11-03-1152.gz \
  --uri='mongodb://<mongo-user>@localhost:27017/?authSource=admin'

The requested explicit-password URI form is equivalent, with the same history/process-exposure caveat:

mongorestore \
  --gzip \
  --archive=./mongobackup-2025-11-03-1152.gz \
  --uri='mongodb://<mongo-user>:<mongo-password>@localhost:27017/?authSource=admin'

If no port is published, use the in-container workflow or a reviewed local-only mapping. Do not expose MongoDB publicly just to restore a backup. When Docker targets a remote engine, the local workstation’s localhost is not that remote Docker host.

Verify the Restore

Read the restore output for restored namespaces, document failures, and index errors. A restore is not atomic: a failed run can leave partially restored data. Do not blindly rerun it against an existing target.

mongosh \
  --username '<mongo-user>' \
  --authenticationDatabase admin

Explicit-password syntax, if needed:

mongosh \
  --username '<mongo-user>' \
  --password '<mongo-password>' \
  --authenticationDatabase admin

At the mongosh prompt, replace placeholders and inspect the intended database:

show dbs
use <database-name>
show collections
db.getCollection('<collection-name>').countDocuments({})
db.getCollection('<collection-name>').getIndexes()

Compare collection names, expected counts, indexes, and selected application records with backup expectations. Counts alone do not establish completeness. Use a verification account with read access if the restore account cannot query data; database visibility also depends on permissions. The mongosh connection guide documents password prompting.

Archive vs Directory-Based MongoDB Backups

A .gz suffix proves neither gzip integrity nor MongoDB archive format. A Database Tools archive is not a tar archive and is not an exported JSON file. Identify how the backup was created before choosing a restore command.

gzip -t mongobackup-2025-11-03-1152.gz

Passing this check validates the gzip stream only. It does not prove the payload is a valid MongoDB archive.

# Format examples; add the required connection/authentication flags
mongodump --out=./dump
mongorestore ./dump

# A directory containing compressed BSON/metadata files
mongodump --gzip --out=./dump-gzip
mongorestore --gzip ./dump-gzip

Directory dumps contain database subdirectories and BSON/metadata files. Pass the directory path instead of --archive. For an uncompressed Database Tools archive, use --archive without --gzip. If the backup is a tarball of a dump directory, extract that wrapper first, then restore the directory. Do not point --archive at the tarball.

Troubleshooting

  • mongorestore: command not found: install compatible MongoDB Database Tools where the command will run, or use the host workflow. Having the server or mongosh installed does not guarantee the tools are present.
  • Unauthorized / getParameter requires authentication: the server was reached; supply credentials and verify the authentication database. Do not disable authentication.
  • Incorrect authentication database: admin is correct only if that is where this user exists. It is independent of the database in the backup.
  • Wrong username/password: validate the same login with mongosh. Check accidental whitespace and URI encoding; use a prompt to avoid shell interpolation. If login works but restore is denied, investigate authorization.
  • Connection refused or timeout from the host: inspect the published port, host-port number, MongoDB bind settings, container status, and firewall. Run inside the container if host publication is unavailable.
  • Archive header or gzip errors: confirm the backup creation command, check for truncation, and distinguish archive, compressed directory, and tarball formats. Renaming a file does not convert it.
  • Duplicate key errors or existing collections: mongorestore inserts documents rather than updating matching records. Existing documents may conflict; non-conflicting inserts can already have succeeded. Use a clean target or a deliberately reviewed replacement strategy.
  • Missing collections after a reported success: review namespace filters, archive contents as reported in restore output, destination database, and verification privileges. Confirm indexes and counts, not just the final document total.

When --drop is appropriate

Destructive operation: --drop removes target collections that are being restored before loading their backup versions. Current documents in those collections are lost, and a later failure can leave an incomplete restore. It does not remove unrelated collections absent from the backup. Use it only for an intentional replacement with a verified recovery backup, reviewed namespace scope, and coordinated application writes. Do not use it casually against production.

If restoring admin with --drop, credentials can also be replaced by those in the backup, potentially affecting access. Review MongoDB’s drop and access-control documentation before such a restore. The example below must be restricted to the intended application database, not admin.

mongorestore \
  --gzip \
  --archive=/tmp/mongobackup-2025-11-03-1152.gz \
  --username '<mongo-user>' \
  --authenticationDatabase admin \
  --nsInclude='<database-name>.*' \
  --drop

Useful Command Reference

docker ps
docker cp mongobackup-2025-11-03-1152.gz '<mongo-container>:/tmp/'
docker exec -it '<mongo-container>' bash
mongorestore \
  --gzip \
  --archive=/tmp/mongobackup-2025-11-03-1152.gz \
  --username '<mongo-user>' \
  --authenticationDatabase admin \
  --nsInclude='<database-name>.*' \
  --stopOnError

--stopOnError stops on document insertion errors such as duplicate keys; it does not roll back earlier writes. Remove the namespace filter only when restoring all archive namespaces is intentional.

mongosh \
  --username '<mongo-user>' \
  --authenticationDatabase admin
show dbs
use <database-name>
show collections

Final Recommended Procedure

  1. Confirm backup format, tool compatibility, target instance, and namespace scope; keep the original backup.
  2. Test the restore on an isolated compatible target first. Prepare a recovery backup and coordinate writes before touching an existing target.
  3. Choose either the copy-and-exec path or the host path; verify the endpoint from that execution context.
  4. Authenticate using a password prompt and the user’s actual authentication database. Check restore permissions.
  5. Restore with the intended namespace filter and stop-on-error behavior. Use --drop only after explicitly reviewing the replacement consequences.
  6. Check the exit status and full restore output. Verify databases, collections, counts, indexes, and application behavior before returning the target to service.
  7. Remove the temporary container copy once verification is complete, following backup-retention policy; retain the original backup and a sanitized record of the result.