Skip to main content
Version: v0.31.0

Migrate and upgrade OpenWA

This guide walks you through the migrations every self-hosted OpenWA operator eventually runs: upgrading to a new version, moving from SQLite to PostgreSQL, switching media storage or Redis, relocating sessions to a new host, and rolling back when something breaks.

Every procedure here is backup-first. The one piece of state you cannot regenerate is session auth — lose it and you re-scan the QR code for every linked WhatsApp number. So you back up first, change one thing at a time, and verify before you delete the old data.

Back up session auth before anything else

Database rows can be rebuilt; linked-device credentials cannot. Before any upgrade or data move, back up your database and both session-auth directories (sessions/ for the default whatsapp-web.js engine, baileys/ for Baileys, both in the data directory), whichever engine you run. A migration that corrupts auth state forces a fresh QR scan on every session.

Prerequisites
  • A running OpenWA instance you can stop for a short maintenance window. See Deployment.
  • An admin API key that is not restricted to specific sessions or selected chats. The infrastructure endpoints used below (/api/infra/*) require the ADMIN role — a read/send key returns 403. See Authentication.
  • Shell access to the host (or container) and roughly twice your current data size in free disk.
  • Every docker compose command below targets the repository's default docker-compose.yml. If you run the single-container docker compose -f docker-compose.dev.yml up -d stack instead, add -f docker-compose.dev.yml to each of them and write openwa wherever a command names the openwa-api service. docker exec and docker cp name the container instead, which is openwa-api in both files, so keep that name there. Do not carry the flag onto the --profile postgres commands: those services exist only in the production file. The two files also store data differently: a bind-mounted ./data on the host versus the named volume openwa_openwa-data, which has no ./data directory on the host. Mixing them points the stack at the wrong data, and a host path such as ./data/sessions exists only for the bind-mounted stack. A standalone Compose file such as the Traefik or Cloudflare Tunnel example on the Deployment page names its service openwa and sets no container name: write openwa for the service, and in docker exec and docker cp use the container name that docker compose ps shows, or add container_name: openwa-api to that service.
  • This page targets OpenWA v0.31.0. Confirm your running version with GET /api/health and your API key.

Pre-migration checklist​

Run through this before you touch anything. Each box maps to a recovery path if the migration fails.

  • Database backed up — a scripts/backup.sh archive, which holds main.sqlite and the data store (openwa.sqlite, or a pg_dump on PostgreSQL).
  • Session auth backed up — both sessions/ (whatsapp-web.js) and baileys/ (Baileys), not just the engine you run: the first boot on v0.23.5 renames every name-keyed auth directory under both to the session id. A rollback to v0.23.4 or earlier looks for the name-keyed directory, finds nothing, and starts those sessions at a QR code unless this backup is restored.
  • Config saved — your .env and docker-compose.yml.
  • Current version recorded with GET /api/health and your API key (the version field is returned only to a caller presenting a valid key, v0.19.0+).
  • Disk space confirmed — about 2x current data size, so a copy and the original coexist.
  • Rollback target noted — the release you would return to: a git tag for a source-built deployment, or the previous image tag for a pinned one (for example rmyndharis/openwa:0.7.5).
  • Tested in staging — for major upgrades or a database switch, rehearse on a copy first.

Take a backup​

Back up the databases, both session-auth directories, and your config. The data lives under /app/data in the container: in the named volume openwa_openwa-data with the default docker-compose.yml, in the bind-mounted ./data with docker-compose.dev.yml or docker run -v "$(pwd)/data:/app/data". The host has a ./data directory only in the bind-mount cases, so a cp or tar that names ./data finds nothing to copy against the named volume. The repo's scripts/backup.sh ships in the image and reads the data where the app writes it, so it covers every layout. Run it in the container, which is named openwa-api in both Compose files:

# Backups hold credentials: owner-only folder and config copies
mkdir -p ./backups && chmod 700 ./backups

# One archive: both databases (the main one holds every API key
# and the audit log), engine auth, media, plugins and bootstrap
# config. BACKUP_DIR and TMPDIR point at the data volume: the root
# filesystem is read-only and /tmp is memory
docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh

# Copy the archive off the volume: it does not survive losing it
docker cp openwa-api:/app/data/backups/. ./backups/

# Config: the archive does not carry .env or the compose file
cp .env docker-compose.yml ./backups/
chmod 600 ./backups/.env ./backups/docker-compose.yml

On a source install, run ./scripts/backup.sh from the project root; its default ./data is the directory the app writes. The Helm chart's /tmp is an emptyDir on node disk, so there only BACKUP_DIR needs setting:

kubectl exec <pod> -- env BACKUP_DIR=/app/data/backups ./scripts/backup.sh
kubectl cp <pod>:/app/data/backups ./backups
Two databases, one local

OpenWA splits storage into a main database (./data/main.sqlite — API keys and audit logs) that always stays local, and a data database (sessions, webhooks, messages) that is the pluggable one you migrate between SQLite and PostgreSQL. Back up both files when on SQLite; the main DB is never part of the data export below.

scripts/backup.sh captures both databases, engine auth, local media, plugins, and bootstrap config in one archive, and scripts/restore.sh puts it back. Both resolve database paths through the launching environment, ./.env, and the data directory's .env.generated, in that order, using MAIN_DATABASE_NAME / DATABASE_NAME, falling back to the fixed ./data defaults. backup.sh fails hard on a missing source database, and deletes an archive that fails its post-write content check instead of reporting success over it. When the sqlite3 CLI is available (it ships in the production image), the script takes an online-consistent snapshot via sqlite3 .backup instead of copying a possibly-live file; without it the archive carries a CONSISTENCY-WARNING marker that restore.sh --strict refuses to restore. Since v0.11.0 backup.sh exits non-zero where it previously reported success over an empty or partial archive — expect scheduled jobs pointed at the wrong paths to start alerting, and treat that as the fix working. Since v0.19.0 restore.sh refuses to restore over a live database unless --force is passed, and both scripts ship inside the production image. Since v0.23.0 both scripts follow PLUGIN_STATE_DIR: with the knob set, the archive carries the plugin registry and each plugin's persisted storage, and a restore puts them back.

Since v0.23.6 backup.sh checks that BACKUP_DIR (default ./backups) is writable before it stages anything, and exits naming the fix when it is not. Inside the shipped container that default sits on the read-only root filesystem, so the commands above point BACKUP_DIR at the data volume. Under Docker Compose TMPDIR points there as well: the script stages a full copy of the data in TMPDIR, and the Compose file mounts /tmp as a tmpfs charged to the container's memory limit. The volume then needs free space for about the data plus the archive. A run killed outright, such as by a container restart mid-backup, leaves its tmp.* staging directory in TMPDIR; on the data volume it stays there until you delete it.

Since v0.25.0 host-side runs with OPENWA_DATA_DIR resolve the default SQLite files and ./data/... paths read from either env file under that directory. A path passed directly in the environment stays relative to the working directory. Both scripts stop with exit 2 on an unreadable env file or a needed setting they cannot parse; fix it or pass the setting in the environment. backup.sh also removes a partial final archive when tar fails.

With DATABASE_SSL=true, backup.sh verifies the PostgreSQL certificate as the app does. Trust a private CA with NODE_EXTRA_CA_CERTS or PGSSLROOTCERT; PGSSLMODE and PGSSLROOTCERT take precedence. If DATABASE_URL overrides the host, its hostname must match the certificate. Stop engines before copying auth when a clean rollback matters: since v0.24.0 an ENGINE-STATE-NOTE warns of potentially live engine state, but restore.sh --strict still rejects only a possibly torn database.

Since v0.26.0 restore.sh stops before it copies anything, naming the key, when a path from the archive's own .env.generated (MAIN_DATABASE_NAME, DATABASE_NAME, SESSION_DATA_PATH, BAILEYS_AUTH_DIR, STORAGE_LOCAL_PATH, PLUGINS_DIR, PLUGIN_STATE_DIR or BOOTSTRAP_KEY_FILE) leads out of the data directory, passes through a link that does not resolve, or lies inside or around another directory the restore refills. It also refuses an archive configuration that puts the admin key file, .env.generated or database.sql on such a directory. To restore to such a path, set that key in the environment or ./.env, which are honored as before; the default paths and a leftover ./uploads restore as before. The script also refuses every spelling of / (//, /., /.., a link to /) as the data directory, a state directory, a database path or the admin key file, and resolves .. after a symlink as the kernel does. It installs keys, plugins and configuration as the archive holds them, so restore only archives you made.

Since v0.27.0 backup.sh records a non-public POSTGRES_SCHEMA in database.schema inside the archive, dumps only that schema with pg_dump -n (requiring pg_dump 14+ when POSTGRES_SCHEMA is not public), prepends a prelude that renames any existing target schema to <schema>_pre_restore_<timestamp> without CASCADE, and moves CREATE INDEX idx_messages_body_trgm after the schema GRANT statements; restore.sh prints the psql restore command with --single-transaction -v ON_ERROR_STOP=1 and checks before writing anything that psql on PATH is a version that enforces \restrict (13.22+, 14.19+, 15.14+, 16.10+, 17.6+, or 18+) whenever database.sql starts with \restrict . Since v0.28.0 restore.sh also extracts archives with tar -P and unlinks any existing file or symlink at a target path before writing, so a symbolic link inside the existing data directory cannot redirect extracted files outside it.

Since v0.31.0 both scripts read an environment value of only blanks as unset, as the app does for the keys it clears (a Compose forward with nothing set renders one), so the next layer supplies the key: a DATABASE_TYPE of spaces no longer makes the backup of a PostgreSQL install archive its old SQLite file. PLUGINS_DIR and DATABASE_URL (which only backup.sh reads) are the exceptions, and the scripts leave them as written: one exported empty counts as set, so PLUGINS_DIR takes the default directory, as the app reads it, and backup.sh builds the connection from the DATABASE_* settings, where both took the value ./.env named. Under the bundled Compose files, which forward PLUGIN_STATE_DIR empty, restore.sh also stops on a PLUGIN_STATE_DIR in the archive's .env.generated that leads out of the data directory, as the v0.26.0 check above says; it skipped that check there.

Since v0.31.0 restore.sh exits 1 before it writes anything when the archive holds the SQLite data store (openwa.sqlite) while DATABASE_TYPE resolves to postgres (from the environment, ./.env or the .env.generated the restore reads: the archive's copy when it carries one, else the data directory's); it used to write a file the app never reads and end with Restore complete. A PostgreSQL archive restores as before. To restore the SQLite archive, change DATABASE_TYPE and DATABASE_NAME where they are set and run it again: an environment value (a Compose environment: entry, a Helm ConfigMap) outranks ./.env, which outranks the dashboard's .env.generated. To move a SQLite install to PostgreSQL, restore the archive into a SQLite install first, then export, switch and import.

Upgrade to a new version​

Since v0.23.6 the dashboard sidebar shows an admin a link to the release notes when a newer OpenWA release is published (see Dashboard). GET /api/infra/update-check gives the same answer to an ADMIN key with no session or chat restriction: current, latest, updateAvailable and releaseUrl. latest is null until the gateway has reached GitHub once, and always with UPDATE_CHECK_ENABLED=false.

OpenWA ships as a Docker image on Docker Hub (rmyndharis/openwa; also mirrored to ghcr.io/rmyndharis/openwa). The repository's docker-compose.yml builds that image from source rather than pulling it, so how you move to the new version depends on which of the two you run. Either way an upgrade is: back up, move to the new version, restart, verify.

# 1. Back up (see above), then stop the running version
docker compose down

# 2. Move to the new version. The repo's compose file BUILDS the API image from source, so check
# out the release tag (see https://github.com/rmyndharis/OpenWA/releases). `git pull` builds
# whatever the default branch holds that day, migrations included, not a release.
# git stops, naming the file, when a tracked file you edited, such as docker-compose.yml,
# differs in the new release
# One chain: a shell rejects an unedited placeholder, so nothing runs until the tag is filled in
git fetch --tags && git checkout v<new-version> && docker compose up -d --build
# A deployment pinned to a published image instead (rmyndharis/openwa:<version>) bumps the tag
# in its own compose file, then runs: docker compose pull && docker compose up -d

# 3. Verify health and the running version (`version` needs a valid API key)
curl -f http://localhost:2785/api/health -H 'X-API-Key: YOUR_API_KEY'

A healthy instance returns (the version field only appears when the request carries an API key, v0.19.0+):

{ "status": "ok", "timestamp": "2026-06-26T10:00:00.000Z", "version": "0.31.0" }

On Kubernetes, back up first (the kubectl exec lines above), then run helm upgrade openwa ./charts/openwa --reset-then-reuse-values (Helm 3.14+) from a checkout of the new release. The image tag defaults to the chart's appVersion, so the checkout moves it, unless image.tag was set at install: the upgrade keeps that value, so pass --set image.tag=<new-version> as well. Run the health check through kubectl port-forward to the release's Service. helm rollback returns to the previous image but keeps the volume, so a rollback that needs the pre-upgrade databases or session auth restores them from the backup, as in Roll back a bad migration.

Use the new chart defaults: plain --reuse-values keeps the earlier 45 s shutdown grace and capability list without KILL, so a stop reaches SIGKILL. --reset-then-reuse-values applies new defaults and re-applies your explicit values; update any old grace/capability overrides too. With older Helm, supply your values through -f values.yaml.

Run schema migrations​

Schema changes are managed by TypeORM migrations, and the data database runs them automatically at boot: always on PostgreSQL, and on SQLite unless DATABASE_SYNCHRONIZE=true puts it in synchronize mode instead. Since v0.24.0 the main (auth/audit) database also runs its own migration chain at every boot and adopts an existing main.sqlite in place. MAIN_DATABASE_SYNCHRONIZE=true additionally enables synchronize; leave it off for migration-managed production schemas. An upgrade therefore needs no migration command of its own. The commands below are for inspecting the chain, or for running it by hand against a stopped app when a long index build would outlast an orchestrator's startup budget. The production image strips the TypeScript toolchain, so use the :prod script variants, which run the compiled migrations from dist/.

# Run them inside the image: the compiled migrations these scripts point at live in dist/, which
# a cloned repo on the host does not have. `run --rm` also lets you migrate while the app is down.

# Show executed and pending migrations on the data DB
docker compose run --rm openwa-api npm run migration:show:prod

# Apply pending migrations to the data DB
docker compose run --rm openwa-api npm run migration:run:prod

# Roll back the most recent data-DB migration. One migration per run: before repeating it, read
# the schema revert box under "Roll back a bad migration" below
docker compose run --rm openwa-api npm run migration:revert:prod

The main (auth/audit) database has its own migration set. Inspect and run it with the :main:prod variants:

docker compose run --rm openwa-api npm run migration:show:main:prod
docker compose run --rm openwa-api npm run migration:run:main:prod

v0.25.0 creates IDX_messages_session_timestamp_id, IDX_messages_session_chat_timestamp_id, and IDX_messages_session_direction_timestamp_id without concurrent index builds. Allow about 240 MB of additional table/index space per million messages. PostgreSQL writes to messages wait until all three builds commit. The Helm startup probe checks every 5 s for 60 failures by default (about 295 s); run the migrations with all nodes stopped before starting the pod, or raise startupProbe.failureThreshold for a large table. The release also indexes ingress dead letters by delivery id. A first boot that jumps over v0.24.0 also runs that release's two index builds, listed below, in the same boot.

v0.26.0 adds four data-database migrations, which share the boot transaction on PostgreSQL. AddWebhookOutboxSessionIndex builds IDX_webhook_outbox_events_sessionId on webhook_outbox_events, again without a concurrent build, so deleting a session no longer reads the whole table. BackfillLegacyMessageTypes converts the legacy messages.type values to the engine-neutral ones in one UPDATE, once; earlier releases scanned the unindexed column at every boot, before the HTTP port opened. On PostgreSQL that statement lifts the statement timeout for its own transaction and takes about a minute per million legacy rows, with the port closed. Rows an earlier release already converted are not touched again; a large backlog remains only where that boot-time conversion kept being cancelled by the statement timeout. Count the rows with SELECT count(*) FROM messages WHERE type IN ('chat', 'buttons_response', 'list_response', 'template_button_reply', 'ptt', 'vcard', 'multi_vcard'); above a few million, run the migrations first or raise startupProbe.failureThreshold to cover the conversion on top of the index builds. AddLidMappingReportSource adds lid_mappings.isReported, false for every existing row: those rows keep their display data but no longer authorize phone and LID aliases until an engine reports the pair. RepairSqliteMessageFts runs on SQLite only: it checks the messages_fts full-text index against messages and rebuilds it when they differ, so a large database starts more slowly while the port is closed; a healthy index costs one integrity check. A SQLite data database under DATABASE_SYNCHRONIZE=true runs no migrations, so there the type conversion runs at every boot and the index check follows each synchronize.

v0.27.0 adds one data-database migration, AddChatStateDeletedAt (1791700000000), which adds a nullable deletedAt column to chat_states (BIGINT on PostgreSQL, integer on SQLite) so that deleting a chat hides it from GET /api/sessions/{sessionId}/chats on Baileys until a newer message arrives in that chat. When SEARCH_CONTAINS_ENABLED=true, startup also builds the message substring trigram index (pg_trgm and unaccent GIN index idx_messages_body_trgm via CREATE INDEX CONCURRENTLY on PostgreSQL, or messages_trgm FTS5 tokenize='trigram remove_diacritics 1' table on SQLite 3.45+) in the background after the HTTP port opens. v0.28.0 adds one more data-database migration, AddStatusMediaPathIndex (1791800000000), a partial index IDX_status_updates_mediaPath on status_updates.mediaPath (rows where it is not null) for the status media orphan sweep, created when the gateway starts. v0.27.1, v0.29.0, v0.29.1, v0.30.0, v0.30.1, v0.30.2, v0.30.3, and v0.31.0 add no new database schema migrations. Since v0.28.0 the migration CLI (npm run migration:run / migration:run:prod and :main:prod) stops naming .env or data/.env.generated when either exists on disk as a directory or cannot be read by the user running the CLI: run it as the file's owner or inside the image.

Since v0.24.0 boot refuses a main database whose migration ledger comes from a newer release or whose recorded columns are missing. Restore the matching pre-upgrade main database. Do not revert main migrations to get past the guard: the oldest main migration drops api_keys and audit_logs, and every revert reports success. Do not remove ledger rows to bypass the guard either.

Upgrade to v0.31.0​

  • Back up both databases and both engine-auth directories (sessions/ and baileys/) before starting the new version. v0.31.0 adds no database schema migrations. On linux/amd64 the image moves Chrome for Testing from 157 to 158 (158.0.8127.36, from 157.0.8103.78 in v0.30.1 through v0.30.3), and a source install that runs the Chrome Puppeteer downloads (no PUPPETEER_EXECUTABLE_PATH) moves from Chrome 156 to 157 with Puppeteer 25.17.0, so a rollback to v0.30.3 or earlier crosses a browser major and clears stored whatsapp-web.js logins unless sessions/ is restored from a backup taken before the first start on v0.31.0 (an amd64 rollback to v0.28.0 or earlier needs one taken before the first start on v0.29.0 or later; see Roll back a bad migration). On a source install, back up SESSION_DATA_PATH (default data/sessions/) before the first start and restore it before downgrading. The linux/arm64 image runs the chromium Debian ships when it is built, whose major can differ between releases; Baileys sessions are unaffected.
  • whatsapp-web.js 1.34.8 ends its wait for the page's connection to WhatsApp to open after WWEBJS_AUTH_TIMEOUT_MS (30000 ms unless set), where 1.34.7 waited with no limit of its own. A start on a host where that connection takes longer now fails (the start answers 504), and a session that ends failed is not started again at boot by AUTO_START_SESSIONS. Raise WWEBJS_AUTH_TIMEOUT_MS there, then start the session.
  • scripts/restore.sh exits 1 before it writes anything when the archive holds the SQLite data store and DATABASE_TYPE is postgres, where v0.30.3 exited 0 after writing a file the app never reads. A rollback to a SQLite backup taken before a move to PostgreSQL meets this: change DATABASE_TYPE and DATABASE_NAME where they are set, then run it again (see Take a backup).
  • The local media store (STORAGE_LOCAL_PATH, ./data/media by default) is owner-only: the gateway sets its root 0700 at every boot, whatever STORAGE_TYPE is, when it owns the directory (a directory it does not own keeps its mode and a warning is logged at boot), and writes new directories and files 0700 and 0600. The storage export archive is written 0600 in a 0700 data/exports, where it was 0644 in 0755, and the next boot closes the directory of an archive an earlier version left. A process that reads the media directory or the export archives as a user other than the one the gateway runs as, such as a static file server or a backup job under another uid, loses access: run it as the gateway's user (the image runs as openwa). Files written earlier keep their mode but sit under the 0700 root. With STORAGE_TYPE=s3 the directory matters only while it still holds files: those stored before the move to s3 and the fallback written while the bucket was unreachable.
  • The built-in S3 storage image (pgsty/silo) moves from RELEASE.2026-09-16 to RELEASE.2026-11-12, a security release. An existing openwa-minio container keeps the image it was created from until it is recreated. With the Compose minio profile, run docker compose --profile minio pull minio && docker compose --profile minio up -d minio. For a container the dashboard created, run docker rm -f openwa-minio, then restart OpenWA, which creates it again from the pinned image (until then the boot logs a warning that the images differ). The openwa_minio-data volume and its media are kept either way.
  • With the queue on (QUEUE_ENABLED=true), an ingress event row stays pending, with its payload, until the worker settles it, where it was marked dispatched with its payload cleared as soon as its job was queued. A queue job that Redis loses (a restore from an earlier snapshot, a failover to a replica that was behind, a restart without persistence) is now replayed from its event row instead of dropping the delivery, and while Redis cannot be asked the reconciler replays nothing inline, where it used to. With the queue off, a pending ingress row, like a stranded webhook outbox row, is replayed inline whatever Redis still holds, so a job left in ingress-queue or webhook-queue runs again when the queue is turned back on: let both queues drain before turning it off (see Switch Redis).
  • The SSRF guard also refuses the documentation and benchmarking blocks (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32, 3fff::/20, 2001:2::/48, also in their 6to4, NAT64 and IPv4-mapped spellings) and the 6a44 relay anycast address 192.88.99.2, as it already refused 198.18.0.0/15: a webhook, media or plugin url that points into one is refused, and a receiver on such an address needs SSRF_ALLOWED_HOSTS.
  • With STORE_EPHEMERAL_MESSAGES=false (the default is true), Baileys no longer keeps an incoming message of a disappearing-messages chat: no copy in baileys_stored_messages (where it stayed, and in backups), no text as the chat's lastMessage, and no media download. A reply, forward, reaction, star, pin, unpin, delete by id, button click or quote of such a message, a group read receipt that names one, and an encrypted edit, reaction or vote aimed at it no longer work, and an RSVP to an event posted there is not reported. Messages the account sent itself and statuses are not dropped. Keep the setting at true if consumers act on messages of disappearing chats. Rows stored before the upgrade stay until BAILEYS_MESSAGE_STORE_LIMIT evicts them.
  • A whatsapp-web.js unblock (DELETE /api/sessions/{sessionId}/contacts/{contactId}/block) now unblocks only the entry under the number's privacy id: v0.26.0 through v0.30.3 also unblocked an entry the same person held under a second id, such as a phone-keyed block from before the LID migration. A contact that stays blocked after an unblock needs that entry unblocked on the phone. Block and unblock on whatsapp-web.js also answer 400 for a number that WhatsApp, asked for it, holds no privacy id for.
  • Baileys lists name as "" for a chat held under a privacy id that has no saved, verified or push name, with its phone when the session maps the id, where v0.30.3 listed the id's own digits: title such a chat by phone, else by id. This reaches GET /api/sessions/{sessionId}/chats, the MCP SessionGetChats tool and a plugin's getChats. Every Baileys chat name is also trimmed, and a blank name of any other chat lists the contact's name or the id's digits, where v0.30.3 listed it as it came, so an empty-name check on a chat not held under a privacy id no longer matches.
  • An MCP MessageList call that does not set inlineMedia returns each media message with an { omitted, sizeBytes } marker in place of its payload, where v0.30.3 returned the base64 inline up to the 8 MiB budget. Pass inlineMedia: true to get the bytes. GET /api/sessions/{sessionId}/messages still inlines by default.
  • The retryable 409 a whatsapp-web.js session answers while WhatsApp Web reloads its page (to a request that sent nothing, or a read or write that converges when repeated) has a new message (Retry every few seconds: this can last a few minutes.) and carries code ENGINE_PAGE_RELOADING and retryAfterSeconds (5). A client that matched the old text, Retry in a few seconds., must match the code. A send, reply or forward whose first attempt had already run when the page reloaded answers a 409 with no code that says the message may or may not have been sent: check the chat before sending it again.
  • Plugin config lists with a secret column no longer hand a stored secret to a row that is not its row: removing one row and adding another no longer gives the new row a kept row's secret, and a stored secret sits on at most one row. The cost is that, in a save of the same length in which a row that matches a stored row by its other fields changes position (for example removing a row ahead of a kept one and adding another, or reordering rows), a row renamed in place is saved with its mask untouched but without its secret, and so is a row that differs from another only by its secret and was edited or removed in such a save: enter those secrets again.
  • An installed plugin whose manifest declares ingress that is not a list, an hmac-sha256 contentTemplate that is not a string, or a header, timestampHeader (hmac-sha256 and shared-secret routes), dedupHeader or conversationId.header that is not a string fails to load at boot (status error, and the log names the field and, where the field belongs to a route, the route); v0.30.3 did not check these fields, so such a manifest could fail to load, fail at runtime or be read as if the field were absent. Correct the field and update the plugin. An install or an update of such a package answers 400 naming the field.
  • A plugin ctx.storage key that holds a lone UTF-16 surrogate (half of an emoji left by slice) is refused: set and delete reject it as an unsafe key and get answers null. A record an earlier version wrote under one stays reachable through the key spelled with U+FFFD.

Upgrade to v0.30.1, v0.30.2, or v0.30.3​

  • v0.30.1, v0.30.2, and v0.30.3 add no database schema migrations. On linux/amd64 their images run Chrome for Testing 157.0.8103.78, where v0.30.0 ran 157.0.8103.50, the same major.
  • Baileys reports poll votes as poll.vote, as whatsapp-web.js already did (v0.30.2+). A vote is read while the poll's creation message is still in the session's message store (BAILEYS_MESSAGE_STORE_LIMIT), and earlier votes are not backfilled. On both engines poll.vote carries at most 32 selectedOptions of 1024 characters each and a pollName of at most 1024 characters (v0.30.2+).
  • On whatsapp-web.js, a group or security notice WhatsApp Web draws in a chat is no longer returned by the chat history or reported as a chat's last message (v0.30.2+; live delivery of notices had already stopped in v0.28.0), and an entry of a kind the library does not list that carries neither text nor media is no longer stored or announced as an unknown message, returned by the chat history, or reported as a chat's last message (v0.30.2+). The header of an album, whose photos and videos arrive as their own messages, is dropped from all of these (v0.30.3+). On Baileys, a message or status that decrypts only in part and is left with no content is no longer stored or announced as an empty unknown message either (v0.30.2+).
  • Some Baileys accounts receive contact statuses as a top-level <status> stanza. v0.30.1 acknowledges it, so the server stops closing the stream about 50 minutes later with Stream Errored (ack). v0.30.2 also decodes it, so those statuses reach the status list and the status.received webhook, and a status that fails to decrypt is dropped, not retried. Both come from the install-time patch scripts/patch-baileys-status-ack.js.
  • The session config key linkPreview (v0.30.3+, set with PATCH /api/sessions/{sessionId}/config) is the default for a send-text or send-template that sets neither linkPreview nor customLinkPreview: a value in the request wins, false sends without a preview on both engines, and null returns to the engine's default.
  • A message:sending plugin that rewrites a send-text to carry both linkPreview: false and customLinkPreview now gets the 400 the same request gets directly (v0.30.3+); Baileys sent it with the supplied preview.
  • PATCH /api/sessions/{sessionId}/config on a session whose stored config is JSON but not an object, as a restored backup can hold, no longer writes the characters of a string or the items of an array back as keys (v0.30.3+).

Upgrade to v0.28.0 or v0.29.0​

  • Back up both databases and both engine-auth directories (sessions/ and baileys/) before starting the new version. v0.28.0 adds one data-database migration, AddStatusMediaPathIndex (see Run schema migrations); v0.29.0, v0.29.1, v0.30.0, v0.30.1, v0.30.2, v0.30.3, and v0.31.0 add no database schema migrations. On linux/amd64 the v0.29.0 through v0.30.3 images move Chrome for Testing from 156 to 157 (157.0.8103.38 in v0.29.0 and v0.29.1, 157.0.8103.50 in v0.30.0, 157.0.8103.78 in v0.30.1 through v0.30.3; v0.31.0 moves it on to 158), so a rollback from v0.29.0 through v0.31.0 to v0.28.0 or earlier crosses a browser major and clears stored whatsapp-web.js logins unless sessions/ is restored from a backup taken before the first start on v0.29.0 or later (see Roll back a bad migration).
  • On whatsapp-web.js (v0.29.0+), OpenWA checks the HTML fetched from wppconnect-team/wa-version before pinning it and rejects any build whose HTML is WhatsApp's logged-out landing page (<html id="whatsapp-web-logged-out">, quoted or unquoted in v0.29.1+, logged as web_version_html_rejected), stepping back up to 3 older settled builds on auto/latest (from the same registry read without a second fetch in v0.29.1+) or falling back to WhatsApp's live page (web_version_html_unavailable) when an explicit version is pinned. Also in v0.29.0, a whatsapp-web.js session configured with a credentialed http:// or https:// proxyUrl bypasses WhatsApp Web's service worker so in-page fetch() media downloads authenticate through the proxy instead of failing with 407.
  • In v0.29.1+, message.received and message.sent (webhooks and WebSocket) on both engines, and live chat history (GET /api/sessions/{sessionId}/messages/{chatId}/history, whatsapp-web.js only), include isForwarded: true and (when positive) forwardingScore on forwarded messages, and Baileys session start on SQLite seeks stored chat names by (sessionId, chatId) instead of scanning all incoming messages in the session when the account has many chats it only ever sent to.
  • In v0.30.0+, Baileys sets restriction: { kind: "passkey_required", code: "passkey_prologue_request", expiresAt: null } (and dispatches session.restriction) when WhatsApp requests a passkey during linking, logs baileys_link_restart on post-link 515 restarts and stage + aliveMs on baileys_connection_dropped (ending lastError on a reconnect-looping session with the stage from the 5th attempt), and applies patch-baileys-media-stream.js (14 install-time patches in all) so an abandoned or cut-off inbound media download on Baileys v7 destroys its HTTP stream cleanly instead of crashing the gateway with TypeError: terminated. Also in v0.30.0+, MCP tool schemas set additionalProperties: false and refuse unknown arguments or payloads over 10,000 array items and object keys, MessageList adds inlineMedia and the REST list filters, MessageSearch adds type, all 11 MCP send tools accept idempotencyKey, MessageSendTemplate accepts linkPreview, SessionGetPresence returns observedAt as an ISO date-time string, GroupFindAll returns 404 for an unknown session, and the inline MCP text threshold rises from 4 KiB to 32 KiB.
  • Boot and the migration CLI (npm run migration:run and migration:run:prod) now fail fast, naming the file (Cannot read <path>: <reason>), when .env or data/.env.generated exists on disk as a directory (for example a single-file Docker bind mount where the host file was missing) or cannot be read by the runtime user (v0.28.0+).
  • The first boot with API_MASTER_KEY set no longer prints the key in the startup banner, later boots print no prefix of it, and GET /api/auth/api-keys lists a key seeded from it as (master key) instead of its first 12 characters (v0.28.0+). Read the key from the environment or Secret that set it, or from /app/data/.api-key (BOOTSTRAP_KEY_FILE).
  • POST /api/infra/import-data (v0.28.0+) validates every session id (1..128 ASCII letters, digits, and hyphens) and every JSON column (sessions.config, webhooks.events/headers/filters, messages.metadata, message_batches.messages/options/results, templates.variables, plugin_instances.config, automation_rules.conditions) before opening the transaction, refusing an invalid archive with imported: false and warnings without clearing the target tables. It also clears inherited secrets on disabled or non-wildcard (sessionIds) plugin_instances rows unless an existing instance row matches the same id, pluginId, and config origin.
  • scripts/restore.sh (v0.28.0+) extracts archives with tar -P and unlinks any existing file or symlink at a target path before writing so a symlink inside the existing data directory cannot redirect extracted files outside it.
  • Request validation in v0.28.0+ refuses: a JSON body with more than 10,000 items in one array, more than 1,000 keys on one object, or more than 250,000 array items and object keys in total (400); a POST /api/sessions config over 16,384 bytes serialized (400); a webhook write with more than 27 events or a webhook or automation rule id filter value over 128 characters (400); GET /api/sessions/{sessionId}/contacts/check/{number} (and MCP openwa_contacts_check) with a group, channel, @lid, or two-@ id or a value with no digits (400); any group route or MCP tool whose {groupId} does not name a group (400, where the engine returned 403 or 404); POST /api/sessions/{sessionId}/messages/send-sticker on whatsapp-web.js with non-image/non-video media (400); POST /api/sessions/{sessionId}/chats/pin or .../chats/mute on Baileys for an unpaired 1:1 chat (400); POST /api/sessions/{sessionId}/messages/edit on Baileys when the target message has no text or caption (403, matching whatsapp-web.js); and POST /api/sessions/{sessionId}/channels/{channelId}/owner/transfer or .../admins/demote when {channelId} does not end in @newsletter (404). Meanwhile, /api/sessions/{sessionId} routes accept any id of 1 to 128 ASCII letters, digits, and hyphens and answer 404 (not 400) when no session has that id.
  • On whatsapp-web.js (v0.28.0+), system notices (e2e_notification, notification_template, broadcast_notification) are no longer delivered as type: "unknown" on message.received, message.sent, or message.ack. On Baileys (v0.28.0+), message.ack now reports delivered and read for a group message the account sent once every non-self member in the group roster has delivered or read it, and a non-admin attempt to delete another member's group message for everyone is ignored instead of emitting a false message.revoked.
  • PUT /api/plugins/{id}/config on a built-in engine plugin (whatsapp-web.js or baileys) deep-merges nested plain objects (puppeteer, baileys) into the stored config instead of replacing them, clears a key at any depth when set to null, and falls back to PUPPETEER_HEADLESS and PUPPETEER_ARGS from the environment for keys omitted from a partial puppeteer override (v0.28.0+).
  • http_requests_total (v0.28.0+) records status="499" when the client closes the connection before the response is sent, 408 or 503 when the in-flight body budget drops or sheds a body, and route="(unmatched)" for unmatched routes, and openwa_ingress_dedup_body_mismatches_total counts ingress deliveries that reuse a deliveryId with a different payload hash.

Upgrade to v0.27.1​

  • Adds GET /api/sessions/{sessionId}/contacts/{number}/lid ({ lid: string | null }), the reverse of GET .../contacts/{lid}/phone; on whatsapp-web.js, GET .../contacts/{lid}/phone also answers { phone: "<digits>" } directly when passed a phone number or @c.us JID.
  • POST /api/infra/restart answers 409 with code: "RESTART_DATABASE_NOT_STARTED" when DATABASE_TYPE=postgres and POSTGRES_BUILTIN=true (pointing at the bundled host) and the openwa-postgres container is not running, or code: "RESTART_ALREADY_RUNNING" when a restart is already in progress.
  • POST /api/sessions/{sessionId}/messages/forward stores the original message's type, text (body), and media metadata (mediaUrl, mimeType, filename) on the new row instead of hardcoded type: "text" and body: "[forwarded]".

Upgrade to v0.27.0​

  • Back up both databases and both engine-auth directories (sessions/ and baileys/) before starting the new version.
  • AddChatStateDeletedAt adds chat_states.deletedAt on the data database. When SEARCH_CONTAINS_ENABLED=true (default false), the gateway builds the message substring trigram index in the background after the HTTP port opens, and GET /api/search?match=contains answers 501 until the index is ready. On PostgreSQL the build requires CREATE on the schema and the pg_trgm and unaccent extensions (idx_messages_body_trgm); on SQLite it requires SQLite 3.45+ (messages_trgm).
  • Outbound messages sent through the API now store the session's own <phone>@c.us (when the session's phone is known) in messages.from instead of the bare phone number, matching messages sent from a linked phone and incoming messages; from filters on GET /api/sessions/{sessionId}/messages and GET /api/search match both forms.
  • The message.ack webhook and WebSocket event and the message:ack plugin hook now fire only for messages the session sent itself (fromMe: true). Delivery receipts for incoming messages no longer emit message.ack.
  • When a message edit arrives and updates a stored message's text, the message:persisted plugin hook fires again with metadata.edited: true.
  • DELETE /api/plugins/{id} clears the plugin's operator settings in plugins/registry.json first, then unloads the worker and deletes the plugin directory on disk (if that initial registry.json write fails, DELETE answers 500 and the plugin stays running). If removing the files fails after the registry entry is emptied, DELETE answers 400, the audit log records partial: true with fileDeleteError, and the plugin stays disabled and does not reload on the next boot.
  • On the built-in engine plugins (whatsapp-web.js and baileys), PUT /api/plugins/{id}/config removes a stored top-level key when its value is null so that the setting falls back to .env, and ignores *** when no secret is stored instead of writing the literal mask.
  • Outbound media uploaded from a send, status post, or bulk send with archived: true is now deleted by the daily media retention job after CHAT_MEDIA_ARCHIVE_TTL_DAYS alongside inbound archived media.
  • The PostgreSQL pool sends statement_timeout, TimeZone='UTC', and search_path as SQL statements on each new connection instead of startup packet options, so PgBouncer in session pooling mode works without ignore_startup_parameters. Transaction pooling remains unsupported because boot migrations and background trigram index builds use session-level advisory locks.
  • backup.sh records a non-public POSTGRES_SCHEMA in database.schema, dumps only that schema with pg_dump -n (requiring pg_dump 14+ when POSTGRES_SCHEMA is not public), prepends a prelude that renames any existing target schema to <schema>_pre_restore_<timestamp> without CASCADE, and moves CREATE INDEX idx_messages_body_trgm after schema GRANTs; restore.sh prints the psql command with --single-transaction -v ON_ERROR_STOP=1 and requires a psql version that enforces \restrict (13.22+, 14.19+, 15.14+, 16.10+, 17.6+, or 18+) when database.sql opens with \restrict .

Upgrade to v0.26.0​

  • Back up both databases and both engine-auth directories (sessions/ and baileys/) before the first start, as for every upgrade. On amd64 the image moves from Chrome for Testing 153 to 156, so a rollback to v0.25.0 or earlier crosses a browser major and deletes the stored whatsapp-web.js logins unless sessions/ is restored from a backup taken before the first start on the new image (see Roll back a bad migration). Baileys sessions are unaffected, and the arm64 image keeps the chromium package Debian ships. A source install that uses Puppeteer's downloaded browser moves from Chrome 146 to 156: back up SESSION_DATA_PATH (default data/sessions/) before the first start and restore it before downgrading. An explicit PUPPETEER_EXECUTABLE_PATH keeps selecting that browser.
  • Breaking (config): a production boot refuses a METRICS_TOKEN that is the .env.example placeholder or a known weak value such as test or change-me, since the scrape endpoint is public. Set a long random token, or unset it to keep /api/metrics disabled (it answers 404).
  • A boot with REDIS_TLS=true or a REDIS_USERNAME other than default beside the built-in Redis (REDIS_BUILTIN=true with the bundled host, while Redis, the queue or the cache is on), or with DATABASE_SSL=true beside the built-in PostgreSQL (DATABASE_TYPE=postgres and POSTGRES_BUILTIN=true with the bundled host), is refused, because those containers run without TLS and the Redis one has only its default user. Clear the setting, or use an external server. A save of the Infrastructure page that the next boot would refuse is refused too. A boot with STORAGE_TYPE=s3 and an S3_ENDPOINT without http:// or https:// (for example minio:9000) still starts, on the local media directory, and logs an error; add the scheme.
  • A POSTGRES_BUILTIN, REDIS_BUILTIN or MINIO_BUILTIN flag starts its container at boot only while the datastore is in use (PostgreSQL selected; Redis, the queue or the cache on; S3 storage) and its host is not pinned to another server. A container nothing used is no longer started, and a restart from the Infrastructure page stops one the dashboard created whose host is pinned elsewhere.
  • STORAGE_LIST_MAX_FILES is gone: a leftover value is ignored instead of validated at boot, and the bundled Compose files no longer forward it. BAILEYS_GROUP_METADATA_CACHE_TTL_MS (default 300000, forwarded by both Compose files) lets a Baileys group send reuse the group's participant list for up to 5 minutes; set it to 0 to query for every send as before.
  • QUEUE_PREFIX sets the Redis key prefix of the BullMQ queues (1 to 64 letters, digits, dots, underscores or hyphens, starting with a letter or digit; anything else fails the boot). Unset keeps bull, so jobs queued by an earlier version are still found. Changing it on a live deployment leaves the jobs queued under the old prefix unprocessed: drain both queues first, as in Switch Redis.
  • The bundled Docker socket proxy no longer allows INFO: GET /info through it is refused, and a client of your own that reads it needs INFO: 1 on the proxy.
  • The HTTP port now opens after at most 60 s of plugin restore, and plugins still restoring finish in the background. Until one is up, the hooks it owns (a send moderation veto, for one) do not run, an enable, disable, update, uninstall or reinstall of it answers 409, an ingress route with a response contract answers 503 with Retry-After, and other ingress deliveries are held and dispatched once it is up (with the queue off, by the reconciler after INGRESS_RECONCILE_GRACE_MS). Held queued jobs spend no retry attempt and wake together. Do not rely on a plugin veto while a plugin is still restoring after a boot with slow plugins. See Plugin changes answer 409 just after a restart.
  • An explicit null for a secret field of a plugin config removes the stored secret, where v0.25.0 kept it; the mask, an empty string and an absent key still keep it, so a client that sends null for "not provided" must leave the key out.
  • A per-session plugin config or an integration instance that sets a net.allowConfigHosts key (for example baseUrl) to another origin than the layer beneath no longer inherits that layer's secret fields, and a write that moves such a key to another origin no longer gets the stored secret back for *** or an empty string. Put the secret in that config or instance and send it with the write; a deployment that shared one token across per-session hosts must copy the token to each. A config PATCH of an instance whose plugin is not loaded answers 409.
  • A client that connects to the Socket.IO root namespace / is refused (Invalid namespace); connect to /events, which closes a connection whose client frame passes 8 KiB. The subscribe frames of the dashboard and the SDKs are under 1 KB.
  • Request validation is stricter, and these answer 400 where they were accepted or answered 500: a JSON boolean or object in a string field ({"text":{"a":1}} sent [object Object]; a JSON number is still converted), an array in a nested object field (for example bulk options, a bulk item's content and media, customLinkPreview, the infrastructure config sections or a status media source) and an object in a list field (for example a webhook's events), a body nested more than 100 levels, a muteUntil above 9007199254740991, a chatId, fromChatId or toChatId that is not localpart@host or is a JSON number, and an object sent for allowedChats, allowedSessions or allowedIps on an API key, which was stored as an empty list, meaning no restriction. POST .../groups/{groupId}/membership-requests/approve and /reject answer 400 for a JSON list body or a content type other than JSON or form encoding, where they acted on every pending request; send {} or no body for that. GET /api/sessions/{sessionId}/contacts/profile-pictures leaves out an id it skipped after another lookup timed out, so a client must handle a missing key.
  • On whatsapp-web.js, POST /api/sessions/{sessionId}/pairing-code answers 409 for a number that is the stored phone of another session of the gateway; log that session out or delete it first, or link by QR.
  • Session deletion removes the messages, webhook outbox events and webhook delivery failures of the session in bounded batches (at most 2000 rows a statement on SQLite, sized to the time the last batch took, and 500 on PostgreSQL) before the final transaction. Earlier batches stay committed after a later failure: repeat DELETE to finish, or POST /api/sessions/{sessionId}/start to keep the remaining session, which a failed delete otherwise keeps stopped. Size client and proxy timeouts for large histories.
  • On SQLite, POST /api/sessions, DELETE /api/sessions/{sessionId} and DELETE /api/integration/plugins/{pluginId}/instances/{instanceId} wait up to 10 s for another open database transaction and answer 503 when it stays open. The create stores nothing and the instance delete deletes nothing; a session delete may already have committed earlier batches. Retry after the transaction ends.
  • During a rolling upgrade, v0.25.0 nodes can explicitly start or take over sessions marked deleting or deleting-stopped without clearing those records. Upgrade every node before relying on delete holds, removal fences or serialized batch cleanup.
  • The first boot converts the legacy message types in one statement (on PostgreSQL inside the boot transaction, about a minute per million legacy rows with the port closed), builds the webhook_outbox_events session index and, on SQLite, checks the message search index against all stored text and rebuilds it when they differ. Raise startupProbe.failureThreshold or run the migrations first; see Run schema migrations.
  • LID mappings inherited from older versions, or restored from a backup without report-origin data, no longer authorize phone aliases until an engine reports the pair. Upgrade every reader together: older versions do not enforce the origin flag.
  • A storage export or file count answers 409 on a symbolic link inside the local storage directory, on a directory the app cannot read and on one nested 20 levels deep; see Migrate media storage below.
  • restore.sh stops before it copies anything when a path from the archive's own .env.generated leaves the data directory, passes through a link that does not resolve, or lies inside or around another directory the restore refills. Set that key in the environment or ./.env to restore there; see Take a backup.
  • The idempotency key of recurring webhook events (edits, reactions, session and group changes) ends in a random id minted per dispatch instead of an ISO timestamp, and the id stays the same across the retries of one dispatch. A receiver that reads its last segment as a time must dedupe on the whole key.
  • An ingress route's conversationId JSON pointer is read by RFC 6901 tokens, so a trailing or doubled slash names an empty key; a delivery such a pointer no longer resolves takes the per-instance lane. POST /api/integration/instances/{pluginId}/{instanceId}/redrive replays and counts only the dead letters written under the instance's current session binding.
  • A plugin catalog with an entry whose id, name, version or text field is not text is refused with 400; a private PLUGIN_CATALOG_URL catalog must correct the entry, and a null optional field is dropped instead of answered.

Upgrade to v0.24.0 or v0.25.0​

  • Back up both databases and engine auth before starting the new version. v0.24.0 moves the main database to migrations and cleans revoked-message content and invalid LID mappings.
  • An engine credential path set through PUT /api/plugins/:id/config (sessionDataPath for whatsapp-web.js, baileys.authDir for Baileys) is no longer used; before upgrading, move those session folders to SESSION_DATA_PATH or BAILEYS_AUTH_DIR, or point the variable at them, or the sessions need a new link.
  • A config saved with PUT /api/plugins/whatsapp-web.js/config or PUT /api/plugins/baileys/config before v0.24.0 stored every environment-derived engine setting of that time, such as the puppeteer settings, which still override .env; with OpenWA stopped, remove the keys you did not set on purpose, or the whole config, from that plugin's entry in plugins/registry.json under PLUGIN_STATE_DIR (default ./data).
  • The first boot of v0.24.0 builds two indexes, (sessionId, chatId, createdAt) on messages and (sessionId, createdAt, id) on baileys_stored_messages, not concurrently; on a large table boot takes longer, and on PostgreSQL writes to that table wait until the build finishes.
  • Keep MESSAGE_RETENTION_DAYS=0 to retain messages and finished bulk batches indefinitely; enabling it deletes old rows at startup and daily. Back up before setting it; external search indexes need separate cleanup because retention emits no per-row deletion events.
  • Give Compose and Kubernetes at least 75 s shutdown grace, plus increases to the delay/drain settings. Custom root-start hardened containers need KILL for signal forwarding. See shutdown settings.
  • A stop or force-kill made on v0.24.0 or later survives restarts and takeover until an explicit start. Stops made on v0.23.7 or earlier were not persisted, so AUTO_START_SESSIONS=true can restart those sessions after upgrade.
  • New Baileys pairings default to the linked-device name Ubuntu. Set BAILEYS_BROWSER_NAME=OpenWA before restart only if you need the old name; linked sessions are unchanged.
  • PORT rejects surrounding or whitespace-only padding, and WEBHOOK_SHUTDOWN_DRAIN_MS rejects non-integers such as 30s. Infrastructure saves reject invalid ports/pool sizes and unwritable local storage paths.
  • PostgreSQL TLS now matches DATABASE_HOST even when it is an IP address. Use the certificate's DNS name or add the IP to its SANs; a certificate for localhost does not match an IP.
  • Nest framework log lines (route mapping, unhandled exception stacks) now use the OpenWA format: JSON when LOG_FORMAT=json, or with it unset under NODE_ENV=production, and [OpenWA]-tagged text otherwise; a log parser keyed on the [Nest] prefix needs updating.
  • With QUEUE_ENABLED=true, ingress job ids changed format in v0.23.7. When upgrading from v0.23.6 or earlier, let pending ingress rows drain first (no row pending for INGRESS_RECONCILE_GRACE_MS, 60000 ms by default, the age a pending row must pass before it counts as stuck), or a delivery replayed across the upgrade can be dispatched twice.
  • Sessions deleted while the gateway ran v0.23.5 or v0.23.6 left their auth directories on the data volume (fixed in v0.23.7), and upgrading does not remove them: session-<id> under SESSION_DATA_PATH (default data/sessions) for whatsapp-web.js and <id> under BAILEYS_AUTH_DIR (default data/baileys) for Baileys, where <id> is the UUID the deleted session had. No session uses them, but they still hold working credentials for that account, and every backup taken since carries them, until the device is removed under Linked devices on the phone; do that only if you know no live session uses that number. The gateway never loads these directories, because no session has their id. The core v0.23.7 upgrade note suggests removing them and dropping the backups that carry them; that is safe only for a directory you can match to a session you deleted in that window, because a live session's directory has the same shape and deleting it forces a new QR scan, so leave every directory you cannot match.
  • Aged pending ingress events are dead-lettered before retention prunes them. Some may have reached the plugin already, so check before redriving.
  • Ingress routes read only application/json and application/x-www-form-urlencoded bodies. A delivery that carries a body of any other type, JSON sent as text/plain or an application/*+json type included, now gets 415 where it used to be accepted as an empty body (breaking since v0.24.0). Configure such a provider to send one of the two types. See Integration Fabric.
  • Terminal webhook failures only support manual redrive if event payload retention was enabled before the event was queued and the retention window has not expired. See Webhooks.
Read the release notes before a major upgrade

A major upgrade can change API routes, config keys, or webhook payloads. Check the CHANGELOG and the target release's notes first: read the Upgrade notes (behavior changes) section of each release between yours and the target that has one (v0.24.0 to v0.26.0 also flag those items Breaking), then update your integrations. When in doubt, rehearse the upgrade against a backup in staging before touching production.

Changed in v0.23.6: what to check before you pull the image
  • PostgreSQL is pinned to UTC. Every data connection runs SET TIME ZONE 'UTC', and boot fails, naming the effective zone, when that does not hold (for example behind a pooler that drops session state). Set the database default instead with ALTER DATABASE "<database>" SET TimeZone='UTC'. A gateway, or a database server, that ran outside UTC has timestamps to convert before the first start on this release: see PostgreSQL deployments that ran outside UTC. SQLite deployments, and a PostgreSQL deployment whose gateway and server both ran in UTC, need nothing. The DEFAULT now() columns took the server's zone, so a gateway in UTC alone does not settle it.
  • TZ reaches the container. The bundled Compose files forward TZ, defaulting to UTC; up to v0.23.5 a TZ in .env never reached the container. One left in .env therefore takes effect on upgrade: it moves the pretty log timestamps, the lines NestJS's console logger prints itself (through v0.23.7; from v0.24.0 those are OpenWA log lines and follow the pretty stamps like the rest), and the local day the today message counts cover. Stored timestamps stay UTC. The forwarded value also shadows a TZ line in data/.env.generated, so a Compose gateway that took its zone from that file runs in UTC after the upgrade unless .env or the shell running docker compose sets TZ; move the value to .env to keep it.
  • A mixed-case or padded POSTGRES_SCHEMA is refused, naming the rule: at boot, by the data-DB :prod migration scripts above before they connect, and with 400 when saved from the dashboard's Infrastructure page. The name must start with a lower-case letter or an underscore, continue with lower-case letters, digits and underscores, run to at most 63 characters, and not start with pg_.
  • Rate limits. A 429 from a rate-limit window (the short, medium and long windows, and the ingress instance and ingress-ip buckets) carries a plain Retry-After in seconds next to the suffixed Retry-After-<window>, so a client that honors it now waits (up to an hour at the defaults when the long window shed the request) instead of retrying at once. The send-pacing refusal still reports its wait only as retryAfterSeconds in the body, and the MCP and Bull Board IP limits answer 429 with no Retry-After. The MCP pre-auth per-IP limit also counts each message of a JSON-RPC batch, where it counted each request, so a client that batches reaches MCP_IP_RATE_LIMIT_MAX sooner. Per-client limits key an IPv6 client on its /64: where several clients reach the gateway from one IPv6 network, raise the RATE_LIMIT_*, INGRESS_IP_LIMIT, WS_RATE_LIMIT_HANDSHAKE_MAX and MCP_IP_RATE_LIMIT_MAX limits, and INFLIGHT_BODY_BUDGET_BYTES for concurrent uploads.
  • Outbound traffic. A caller-supplied URL (a media URL on a send, status, profile-picture or group-picture route, or on POST /api/sessions/{sessionId}/media/convert/voice or .../convert/video, and the Baileys link preview of a text send) is fetched through the session's proxy. Set SESSION_PROXY_URL_FETCH=false when a session proxy is a WhatsApp-only route that cannot reach arbitrary media hosts. Through an http or https session proxy the proxy resolves the host itself, so such a fetch keeps the SSRF address check but loses the DNS-rebind pinning of the direct path; a socks4 or socks5 proxy, or SESSION_PROXY_URL_FETCH=false, keeps it. When an admin opens the dashboard, the gateway asks api.github.com for the latest release, caching the answer for six hours (fifteen minutes after a failure). That request goes out directly, not through HTTP_PROXY or HTTPS_PROXY; set UPDATE_CHECK_ENABLED=false where that egress is not wanted.
  • WebSocket clients. Command replies arrive on the message event as well as through the ack callback, so a client that passes an ack and also listens on message sees each reply twice. A socket whose key was deleted, revoked, or had its role, allowlists or expiry changed through this node's API is closed with an UNAUTHORIZED frame at once. The same change made by a direct write to this node's main database closes it within a minute, when a sweep that runs every 60 seconds re-reads the keys behind the open sockets. Key tables are per node, so a change made on another node never reaches this node's sockets: repeat it on each node. On API key authorization changed; please reconnect, reconnect and resubscribe, unless the change now refuses the key at the handshake (an allowedIps list that excludes the client, or an expiry that has already passed; a key that gained allowedChats was refused there through v0.24.0 and connects from v0.25.0). After API key has been deleted or API key has been revoked, and usually after API key has expired, the key itself is refused, so reconnect only with a valid key: every refused handshake counts against the per-IP handshake limit that all clients from that address share. See WebSockets.
  • Ingress. A repeat delivery is answered with the route's declared ack, with the same status and headers as the first, and a route with no declared response answers 202 accepted where it answered 200 duplicate. The gateway keeps no record of a repeat either: the ingress_events dedup row is written by the first delivery of each id, a repeat adds no row or field, and the gateway logs nothing for it unless DATABASE_LOGGING is on. Under PostgreSQL's default logging settings, the database server's own log still shows each repeat, key included, as a unique-constraint error on UQ_ingress_events_instance_delivery. An installed plugin whose ingress manifest declares a route that is not one URL path segment, a non-numeric toleranceSec, a 1xx ack status, an ack body that is not a string, or an ack header value that is not a string or that Node cannot send fails to load at boot, and stays in the error state until the manifest is fixed.
  • Queued webhooks. With QUEUE_ENABLED=true, deliveries queued for a webhook that is then deleted, disabled or unsubscribed from the event are dropped, and after a URL, header or secret change they go out with the new values.
  • Media. A media url that is not an absolute http(s) URL answers 400 on a send, status, profile-picture or group-picture route (in a bulk request, an item whose url is not one refuses the whole request with 400 and nothing is queued, unless the url contains a {: that one is checked once variables are applied and fails its item like any other send failure, which stops the batch there under stopOnError), and media conversion refuses an input that is not a single-file media container with 400.
  • Engines. On Baileys, GET /api/sessions/{sessionId}/contacts (and its MCP and plugin equivalents) lists only contacts with a name saved on the phone; a peer known by pushname alone still resolves through GET /api/sessions/{sessionId}/contacts/{contactId} with isMyContact: false. Also on Baileys, a list prompt (listMessage) and a tapped button, template or list reply (buttonsResponseMessage, templateButtonReplyMessage, listResponseMessage) arrive as type: "text" with their display text in body, where they arrived as type: "unknown", so a consumer that filters on type now sees them as text. Baileys sessions also deliver what WhatsApp queued while they were down, the upgrade window included: messages received meanwhile dispatch message.received and those sent from the phone message.sent, where earlier releases dropped both, so a bot that answers inbound messages answers those too, while an automation rule skips any more than 5 minutes old (see Automation rules). On whatsapp-web.js, POST /api/sessions/{sessionId}/calls/{callId}/reject answers 501, and a WWEBJS_ONBOARDING_CONTINUE_LABELS label is clicked only on a button inside a [role="dialog"] or [aria-modal="true"] container.
  • Plugins. The session:created hook carries the session in the REST shape, without proxyUrl or config. A takeover or resolved conversation recorded on a chat's @lid form also silences bots on its phone form; hand the chat back through the plugin that holds it to release it. A number WhatsApp recycled keeps its earlier owner's @lid mapped to it, so a takeover or hand-back on either owner's chat reaches both.
  • Logs. A failed SOCKS proxy connect no longer writes the proxy password to stdout when BAILEYS_LOG_LEVEL is debug or trace. Logs an earlier release wrote at those levels may hold it; rotate that proxy password.
Breaking in v0.20.0: two config changes to check before you pull the image
  • With WEBHOOK_SSRF_PROTECT=false, deliveries no longer follow redirects: a receiver that answers 3xx now fails the delivery. Set WEBHOOK_SSRF_REDIRECTS=true if the redirect is legitimate. SSRF_ALLOWED_HOSTS entries must also resolve at registration time, and each delivery pins its connection to the addresses the name resolves to for that delivery; a name that does not resolve yet fails the webhook create/update with a 400.
  • Plugin installs from a URL require a #sha256=<64 hex> pin under NODE_ENV=production (the compose default), https: URLs included. Action required: catalog installs without a pin fragment now fail. Pin the URL, or set PLUGIN_INSTALL_REQUIRE_PIN=false. Plain-http: installs already needed the pin since v0.19.0.
Breaking in v0.19.0 — one action required before you pull the image
  • Production boot refuses a set API_MASTER_KEY shorter than 32 characters (unset stays allowed — first boot generates one). If your key is short, strengthen it before upgrading; the boot error names the fix.
  • POST /sessions/:sessionId/messages/send-catalog and PUT /api/settings are removed — both always answered 501, so nothing that worked before stops working. Calls to the old URLs now get 404. GET /api/settings and send-product are unchanged.
  • The session routes' path parameter is uniformly {sessionId} in openapi.json and the Prometheus route labels (22 routes previously mixed {id}). The URLs are unchanged — only generated clients need regenerating. See API conventions.

PostgreSQL deployments that ran outside UTC​

The data tables' timestamp columns are timestamp without time zone, which stores no zone. Up to v0.23.5 the gateway wrote and read the columns it fills itself in its own process's time zone (its TZ, or the host's zone for a host install without one), while the columns PostgreSQL fills (DEFAULT now()) took the server's zone. Since v0.23.6 the data connection binds, reads and defaults every timestamp in UTC, so values written outside UTC, by the gateway or by the server, read shifted by that offset once you upgrade. A deployment whose gateway and PostgreSQL server both ran in UTC is unaffected, as is every SQLite deployment, and no data moves. The image runs in UTC. Up to v0.23.5 the bundled Compose files did not forward TZ, so a TZ in .env left a Compose gateway in UTC. What moved a gateway off UTC was a TZ in its own environment (the compose file's environment block, docker run -e, the Helm chart's env, the shell or service unit of a host install), or a TZ line in a file the gateway loads into that environment at startup: data/.env.generated and, on a host install, the project's .env. A host install with neither ran in the host's zone. The bundled postgres profile starts a server in UTC; a host-installed or managed server keeps whatever zone it was given.

A gateway that ran outside UTC takes the two steps below. A gateway that ran in UTC skips them, and converts only the server-written columns described after them, if its server ran outside UTC. Either way, with every OpenWA node stopped and before the first start on v0.23.6:

  1. Convert the columns the gateway writes itself. Twelve columns hold the gateway process's local wall time: sessions.connectedAt, sessions.lastActiveAt, sessions.claimedAt, sessions.leaseExpiresAt, webhooks.lastTriggeredAt, webhook_outbox_events.lastAttemptAt, ingress_events.lastDispatchAt, message_batches.started_at, message_batches.completed_at, lid_mappings.updatedAt, chat_states.updatedAt and baileys_stored_messages.createdAt. The last three carry a DEFAULT now() that never fires, because their only writer passes the value. Convert all of them except the lease pair (step 2) with the zone the gateway process ran in (its old TZ, or the host's zone for a host install that set none), which resolves daylight saving per row. Leaving lid_mappings.updatedAt and chat_states.updatedAt as they are also mis-ranks the boot preload of both caches, which orders by that column under a cap.
  2. Clear the lease, do not convert it. sessions.claimedAt and sessions.leaseExpiresAt are cluster runtime state. Left as they are, a lease reads shifted by the old offset: east of UTC it reads hours into the future, so every node other than the one named in nodeId treats the session as held elsewhere, and POST /api/sessions/{sessionId}/start answers 409 there until the lease lapses (a container recreated on upgrade takes a new hostname, the default NODE_ID, and counts as another node); west of UTC it reads already lapsed, so a peer can adopt a session that is still running.
-- Replace Asia/Jakarta with the zone the gateway process ran in (its old TZ).
-- With a non-public POSTGRES_SCHEMA, run SET search_path TO <schema>; first.
BEGIN;
UPDATE sessions SET "connectedAt" = ("connectedAt" AT TIME ZONE 'Asia/Jakarta') AT TIME ZONE 'UTC' WHERE "connectedAt" IS NOT NULL;
UPDATE sessions SET "lastActiveAt" = ("lastActiveAt" AT TIME ZONE 'Asia/Jakarta') AT TIME ZONE 'UTC' WHERE "lastActiveAt" IS NOT NULL;
UPDATE webhooks SET "lastTriggeredAt" = ("lastTriggeredAt" AT TIME ZONE 'Asia/Jakarta') AT TIME ZONE 'UTC' WHERE "lastTriggeredAt" IS NOT NULL;
UPDATE webhook_outbox_events SET "lastAttemptAt" = ("lastAttemptAt" AT TIME ZONE 'Asia/Jakarta') AT TIME ZONE 'UTC' WHERE "lastAttemptAt" IS NOT NULL;
UPDATE ingress_events SET "lastDispatchAt" = ("lastDispatchAt" AT TIME ZONE 'Asia/Jakarta') AT TIME ZONE 'UTC' WHERE "lastDispatchAt" IS NOT NULL;
UPDATE message_batches SET started_at = (started_at AT TIME ZONE 'Asia/Jakarta') AT TIME ZONE 'UTC' WHERE started_at IS NOT NULL;
UPDATE message_batches SET completed_at = (completed_at AT TIME ZONE 'Asia/Jakarta') AT TIME ZONE 'UTC' WHERE completed_at IS NOT NULL;
UPDATE lid_mappings SET "updatedAt" = ("updatedAt" AT TIME ZONE 'Asia/Jakarta') AT TIME ZONE 'UTC';
UPDATE chat_states SET "updatedAt" = ("updatedAt" AT TIME ZONE 'Asia/Jakarta') AT TIME ZONE 'UTC';
UPDATE baileys_stored_messages SET "createdAt" = ("createdAt" AT TIME ZONE 'Asia/Jakarta') AT TIME ZONE 'UTC';
-- The lease: cleared, not converted.
UPDATE sessions SET "nodeId" = NULL, "claimedAt" = NULL, "leaseExpiresAt" = NULL, "nodeUrl" = NULL;
COMMIT;

The script assumes a database already on v0.23.4 or later. From an earlier release, leave out each statement whose table or column the database does not have yet: chat_states arrived in v0.23.4, webhook_outbox_events in v0.23.0, the lease columns (nodeId, claimedAt, leaseExpiresAt, nodeUrl) in v0.14.0, ingress_events.lastDispatchAt in v0.11.0 (the table itself in v0.7.18), lid_mappings in v0.4.6 and baileys_stored_messages in v0.3.0. One missing table or column aborts the transaction, so none of the script applies. What the upgrade creates starts empty, with no local-time values to convert.

Run the file once per database. Each conversion statement shifts the stored value by the zone's offset and leaves a plain timestamp that reads like an unconverted one, so a second run shifts every value again. An aborted run changed nothing and can be repeated; if the file completed twice, restore the pre-upgrade backup and start over.

On the bundled Compose stack, run the conversion between steps 1 and 2 of Upgrade to a new version: start the database service on its own, which leaves the gateway down, and feed it the statements saved as convert-utc.sql:

docker compose --profile postgres up -d --wait postgres
docker exec -i openwa-postgres psql -v ON_ERROR_STOP=1 -U openwa -d openwa < convert-utc.sql

openwa is the default DATABASE_USERNAME and DATABASE_NAME; use yours if you changed them. A host-installed or managed server takes the same file through psql.

The remaining eighteen createdAt/updatedAt columns (spelled created_at/updated_at on message_batches) are written by PostgreSQL itself, in the server's zone rather than the gateway's. On a UTC server, which is the image default and what the bundled postgres profile starts, they are already correct and must not be converted. Convert them only if the server itself ran outside UTC, whatever the gateway's zone, with the server's old zone. messages.createdAt has two writers: a live message takes the server default, but a row the Baileys history backfill wrote carries the message's own time, bound by the gateway. Where no session ever ran on Baileys, the column holds only server defaults and takes the same treatment as the other columns in this paragraph. Where the gateway and the server always ran in the same zone, both writers used it, so convert the column with that zone. Otherwise the column holds both conventions, nothing in the row says which, and it takes no bulk update. The residual skew then affects the backfilled rows behind a gateway that ran outside UTC, and the live rows on a server that did, in chat ordering, the today counters and the media retention window.

Once v0.23.6 has started, the columns also hold rows it wrote in UTC, and the conversions above shift those by the old offset as well. Stop every node, then either restore the pre-upgrade backup and convert it as above before starting v0.23.6 again, which discards everything written since the upgrade, or convert only the values below the moment the first node started on v0.23.6, expressed in UTC. That cutoff holds only if every node on an earlier release had stopped by then; after a rolling upgrade the older nodes went on writing the old convention past it, so restore the backup instead. West of UTC that cutoff separates the two conventions exactly; east of UTC a value within one offset after it can be either, so correct those rows by hand or leave them. In messages.createdAt a row the Baileys history backfill wrote since the upgrade carries the message's own time, so it can fall below the cutoff either way. Clear the lease as above in both cases.

Restored data needs its own care:

  • A table that had an archive from a SQLite gateway restored into it holds those rows in correct UTC next to the app's own local-time rows. The two are indistinguishable within the column, so a blanket UPDATE moves the rows that are already right; correct such a column row by row against a known archive, or leave it as it is.

  • An archive a PostgreSQL gateway outside UTC exported before v0.23.6 carries the app-written columns at their true instant, but every DEFAULT now() column behind by the gateway's offset less the server's (a full offset on a UTC server, none where the server ran in the gateway's zone), and each further export and restore before v0.23.6 took the whole table one more gateway offset back. On a table holding nothing but restored rows, apply the inverse to each timestamp column once for each round trip its rows went through, a round trip being an export by such a gateway followed by a restore of that archive (importing the same archive again replaces the rows and adds none), then whatever conversion above the column takes anyway:

    UPDATE sessions SET "createdAt" = ("createdAt" AT TIME ZONE 'UTC') AT TIME ZONE 'Asia/Jakarta';

    The two cancel for the twelve app-written columns, so after a single round trip those take no update, while on a UTC server the DEFAULT now() columns take the inverse once per round trip. The lease of a session any node held while the restore ran kept its live values rather than the archive's, so it takes only the clearing above. messages.createdAt takes the treatment of the other DEFAULT now() columns only in the two cases above where it holds one convention, and no bulk update otherwise. Where the table also holds rows written after the restore, no blanket conversion is safe.

  • Re-export after upgrading to get an archive whose timestamps are the instants they claim. A pre-v0.23.6 archive restored after upgrading still carries its shift, and counts as one round trip above. A pg_dump, or the database.sql in a backup.sh archive, taken before the upgrade holds the same values as the live database did, so a database restored from it takes the conversion above.

A rollback to an earlier release drops the UTC pin: a gateway outside UTC reads the converted columns in its local time again, and a database server outside UTC fills the DEFAULT now() columns in its own zone again, next to rows already converted. Restore the pre-upgrade backup, or run the older release with TZ=UTC, first setting the database default with ALTER DATABASE "<database>" SET TimeZone='UTC' where the server's zone is not UTC.

Migrate SQLite → PostgreSQL​

Move to PostgreSQL when you outgrow SQLite — broadly, more than a handful of concurrent sessions, heavy write volume, or a need for higher write concurrency and high availability. See Horizontal Scaling for what can be shared across instances and how to grow one deployment.

You don't hand-write SQL. OpenWA exposes admin endpoints that export the data database to JSON and import it into whatever backend the running instance is configured for. The flow is: export from the SQLite-backed instance, reconfigure to PostgreSQL, restart, then import.

Only the data database moves: sessions, webhooks, messages, message batches, templates, Baileys stored messages, LID mappings, persisted chat state (v0.23.4+), plugin instances, conversation mappings, ingress events, both delivery-failure queues, the outbound webhook-delivery records, status updates, and automation rules. The main database (API keys, audit logs) stays local and is untouched. Since v0.19.0 the export redacts webhook secret and headers —they are not written to the archive at all— so an exported archive restores its webhooks unsigned with no custom headers: re-set the signing secret and headers on each webhook after the import if you rely on them. Since v0.23.4 a session's proxyUrl is redacted the same way, but only its user:pass part: the scheme and host survive, so a restored session still routes through the proxy you chose and fails loudly on its next start when that proxy needs credentials, instead of connecting direct and putting the host's own egress IP in front of WhatsApp. Re-enter the credentials with PATCH /api/sessions/{sessionId}/proxy after the import. Since v0.23.6 that route, like POST /api/sessions, answers 400 for a proxyUrl whose user name or password holds a % that does not begin a valid percent-escape; write a literal % as %25. Up to v0.23.5 such a value was stored, and every later start of the session failed with an opaque URI malformed. A proxyUrl the URL parser rejects is cleared rather than copied, since it cannot be proven credential-free.

# 1. Export the data DB to a JSON file (admin key required)
curl -s 'http://localhost:2785/api/infra/export-data' \
-H 'X-API-Key: YOUR_API_KEY' > data-backup.json

# 2. Switch the data database in .env:
# DATABASE_TYPE=postgres
# DATABASE_HOST, DATABASE_USERNAME, DATABASE_PASSWORD (required for postgres)
# Do NOT rely on POSTGRES_BUILTIN here: the bundled compose files declare no
# env_file and forward each key explicitly, and that one is not among them, so a
# value in .env never reaches the container. Under Compose the profile below is
# what starts the bundled database.

# 3. Restart with the postgres profile (brings up the bundled DB and reconnects OpenWA)
docker compose --profile postgres up -d

# 4. Import the JSON into the now-PostgreSQL data DB
curl -s -X POST 'http://localhost:2785/api/infra/import-data' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d @data-backup.json

The bundled PostgreSQL container runs without TLS, so with DATABASE_TYPE=postgres, POSTGRES_BUILTIN=true and the bundled host a boot refuses DATABASE_SSL=true (v0.26.0+). Set DATABASE_SSL=false, or point DATABASE_HOST at an external PostgreSQL.

The import is one request, and the target's BODY_SIZE_LIMIT bounds it: 25mb by default, read at boot and applied to every route, with a larger file refused as 413. Compare ls -l data-backup.json with the limit before step 3, because from step 3 the stack runs on the new, empty database. If the file is larger, set BODY_SIZE_LIMIT in .env to at least its size before the restart in step 3 (both bundled Compose files forward it), then set it back and restart once the import is done, since it applies to every route. An explicit INFLIGHT_BODY_BUDGET_BYTES must stay at least twice the file size, since one key may hold at most half of that budget in flight; left unset it follows BODY_SIZE_LIMIT. The same limit applies to the second import below, which adds stopOrphans.

The export file is also a valid import payload — its top-level tables object is exactly what import-data consumes, so -d @data-backup.json works as-is. Every export covers the same sixteen tables, in both tables (the full rows) and counts (how many rows each holds), so you can confirm what you captured. The row arrays under tables are omitted below for brevity — in a real export they hold one object per row:

{
"exportedAt": "2026-06-26T02:30:00.000Z",
"dataDbType": "sqlite",
"tables": {
"sessions": [],
"webhooks": [],
"messages": [],
"messageBatches": [],
"templates": [],
"baileysStoredMessages": [],
"lidMappings": [],
"chatStates": [],
"pluginInstances": [],
"conversationMappings": [],
"ingressEvents": [],
"webhookDeliveryFailures": [],
"webhookOutboxEvents": [],
"integrationDeliveryFailures": [],
"statusUpdates": [],
"automationRules": []
},
"counts": {
"sessions": 5,
"webhooks": 12,
"messages": 1500,
"messageBatches": 3,
"templates": 4,
"baileysStoredMessages": 800,
"lidMappings": 60,
"chatStates": 40,
"pluginInstances": 2,
"conversationMappings": 0,
"ingressEvents": 40,
"webhookDeliveryFailures": 0,
"webhookOutboxEvents": 0,
"integrationDeliveryFailures": 0,
"statusUpdates": 25,
"automationRules": 6
},
"skippedTables": [],
"omittedInlineMedia": { "messages": 0, "messageBatches": 0 }
}

A table that genuinely does not exist in the source database (an older schema that predates it) is skipped and named in the top-level skippedTables array. Since v0.11.0, any other read failure — a lock, I/O error, or timeout — fails the whole export instead of silently recording the table as empty, so a 200 response with an empty skippedTables captured every row. Postgres exports also strip the server-maintained body_ts tsvector column from message rows, so a Postgres export imports cleanly into SQLite.

The export also bounds the inline base64 media it embeds, at EXPORT_INLINE_MEDIA_BUDGET_BYTES (8 MiB by default) shared across messages and messageBatches. It spends that budget newest-first and replaces each over-budget payload with an omitted marker, counting the refusals per table in omittedInlineMedia. A 200 with an empty skippedTables but a non-zero omittedInlineMedia is a complete set of rows whose attachments are not all there, so treat export-data as a data move rather than a media-complete backup. Since v0.26.0 a bulk media field that is a placeholder is charged for the template variables it names. The scripts/backup.sh archive above carries no such budget: it captures the whole data database, by sqlite3 .backup snapshot or pg_dump, with every payload intact.

A successful import echoes the counts it wrote, any per-row warnings, and the orphan-engine reconciliation fields (see below):

{
"imported": true,
"counts": {
"sessions": 5,
"webhooks": 12,
"messages": 1500,
"messageBatches": 3,
"templates": 4,
"baileysStoredMessages": 800,
"lidMappings": 60,
"chatStates": 40,
"pluginInstances": 2,
"conversationMappings": 0,
"ingressEvents": 40,
"webhookDeliveryFailures": 0,
"webhookOutboxEvents": 0,
"integrationDeliveryFailures": 0,
"statusUpdates": 25,
"automationRules": 6
},
"warnings": [],
"notices": [],
"restartRequired": false,
"orphanedEngines": [],
"stoppedOrphanEngines": [],
"failedOrphanEngines": []
}

Check imported before you trust the counts. The import runs as one transaction: if any row fails to insert, the whole import is rolled back and the response is { "imported": false, ... } with the failure listed under warnings, but counts still reports the rows inserted before the rollback, so non-zero counts alone do not mean success. On SQLite every failing row is listed. On PostgreSQL the import stops at the first row the database rejects, and warnings names that row with the database's own error (since v0.23.6; before, such an import answered 500). Verify in this order:

  1. Confirm imported === true. If it is false, the data was not written — read warnings, fix the cause, and re-run the import.
  2. Only then compare the import counts against the export counts to confirm everything landed.

Timestamps travel as UTC. Since v0.23.6 an archive moves between SQLite and PostgreSQL in either direction without shifting, whatever zone the gateway runs in, and exporting a restored database and restoring that archive changes nothing. Before v0.23.6 a restore into PostgreSQL on a gateway that did not run in UTC shifted every timestamp by the host's offset, and each further export and restore on such a gateway shifted it by one more offset. Before you restore an archive that a PostgreSQL gateway outside UTC exported on an earlier release, read PostgreSQL deployments that ran outside UTC.

Since v0.26.0 the import lifts the PostgreSQL statement timeout for its own transaction, so clearing a messages table that has grown to millions of rows no longer outlasts DATABASE_STATEMENT_TIMEOUT_MS (30 s by default) and cancels the restore after the engines of the sessions it drops were stopped; a lock wait keeps that bound. On PostgreSQL a schema that lacks an optional table restores without an error, the clear of the missing table being skipped. An archive taken before the engine-neutral message types has its legacy messages.type values converted as part of the restore, and rows of lid_mappings from an archive without the isReported flag restore as unreported, so they do not authorize phone aliases until an engine reports the pair. Since v0.28.0 the import also validates every session id (1..128 ASCII letters, digits, and hyphens) and every JSON column (sessions.config, webhooks.events/headers/filters, messages.metadata, message_batches.messages/options/results, templates.variables, plugin_instances.config, automation_rules.conditions) before opening the transaction, refusing an invalid archive with imported: false and warnings without clearing the target tables, and clears inherited secrets on disabled or non-wildcard (sessionIds) plugin_instances rows unless an existing instance row matches the same id, pluginId, and config origin.

Import replaces, it does not merge

POST /api/infra/import-data clears the target data tables first, then inserts the payload. Run it only against a fresh target you intend to overwrite, never against a database with live data you want to keep.

Restoring while sessions are running​

The replace deletes every session the backup does not contain — but a WhatsApp engine already running for such a session would keep writing into the freshly restored tables. Since v0.11.0 the import pre-flight checks for this and refuses with 409 Conflict, listing the affected session ids. You have two ways through:

  • Stop them in-request (preferred): pass "stopOrphans": true in the payload. The import stops each orphaned engine before the replace runs, and restartRequired stays false. The response reports the outcome per engine in stoppedOrphanEngines and failedOrphanEngines. Since v0.26.0 each session it stops is recorded as a session_stopped audit entry, even when the import does not commit, and the import waits for the message writes still in flight for the sessions it removes, so no row is left for a removed session. An import that does not commit fails the unfinished bulk batches of those sessions.
  • Proceed anyway: pass "force": true. The orphaned engines keep running until the next process restart, and the response carries restartRequired: true with their ids in orphanedEngines — restart promptly to close that window.

The route has three other 409 refusals that neither flag resolves, so read code in the response body before choosing. IMPORT_WOULD_ORPHAN_ENGINES is the orphan case above. IMPORT_ALREADY_RUNNING and EXPORT_IN_PROGRESS mean another import or a data export is running: wait for it to finish. IMPORT_NESTED_TRANSACTION means another transaction holds the SQLite connection: retry with no other data operation in flight (if the request carried stopOrphans, the orphaned engines were already stopped by then).

# Merge the flag into the export payload, then import
jq '. + {stopOrphans: true}' data-backup.json > data-backup-import.json
curl -s -X POST 'http://localhost:2785/api/infra/import-data' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d @data-backup-import.json

Non-fatal reconciliation details land in notices (unlike warnings, they never roll the import back). One such notice counts normalized statuses: an imported session whose backed-up status was an active one (ready, initializing, qr_ready, authenticating, action_required) is restored as disconnected (since v0.21.0), so it is startable with POST /api/sessions/:id/start or adoptable by AUTO_START_SESSIONS without a process restart. A session whose backup carries a stop record restores as stopped and stays down until an explicit start; since v0.26.0 so does one whose delete failed part-way. After a committed restore, OpenWA also reloads its in-memory LID→phone mirror from the restored lid_mappings rows, so no restart is needed for identity resolution to match the backup. Since v0.31.0 it also drops what it keeps in memory (error, restriction and presence state, and the claim) for each session the restore removed, except one whose engine the import leaves running or that another node holds, so openwa_sessions_restricted stops counting those sessions and no lost-claim warning follows for them.

Migrate media storage (local ↔ S3 / MinIO)​

Media files move with the same export → reconfigure → import pattern, over a tar.gz archive. Local → built-in MinIO, local → external S3, S3 → local, and MinIO → external S3 are all supported.

On S3, first confirm GET /api/infra/status reports storage.s3Available: true. Count, export, and import answer 503 until the bucket has been reachable since boot. This flag stays true until restart; a later outage can make count/export fail with 500 or import return failures.

Check sizeBytes against STORAGE_IMPORT_MAX_TOTAL_BYTES (10 GiB by default) and file count against STORAGE_IMPORT_MAX_ENTRIES (100000), plus each file against STORAGE_IMPORT_MAX_BYTES (200 MiB). Raise a matching cap before importing a larger export. Each file can use about twice its size in memory; leave headroom for running sessions. Export warns when an archive exceeds the lower of the configured cap and shipped default.

Since v0.26.0 a count or an export of the local directory answers 409, naming the path relative to the storage root and the cause, when the directory holds a symbolic link (replace it with the real directory or a bind mount), a directory the app cannot read or one nested 20 levels deep; earlier releases left those files out of the count and the archive without a word. The archive carries each stored key as its entry name unchanged (a backslash, a doubled slash or a leading name: segment is no longer rewritten) and leaves out S3 folder placeholders (keys ending in /) and unsafe keys, which the log names. The file count follows the same rule, so count matches what the archive holds. When S3 is the target, S3_ENDPOINT must be an absolute http:// or https:// URL: a value such as minio:9000 logs an error at start and media goes to the local directory, and the Infrastructure page refuses a save that changes the endpoint to such a value or newly selects S3 beside one.

An aborted import keeps files already written. Raise the named limit before retrying; the same caps stop at the same file again. Under Compose, change forwarded .env values and run docker compose up -d to recreate the container, or edit data/.env.generated and restart; a dashboard restart alone does not refresh the container environment. The response includes failed; imported: false means nothing was written when entries failed.

Since v0.31.0 the export archive is written 0600 in a 0700 data/exports, where it was 0644 in 0755, and the local media directory is owner-only too, so a process that reads either as another user loses access: see Upgrade to v0.31.0.

# 1. Check what you're about to move (admin key required)
curl -s 'http://localhost:2785/api/infra/storage/files/count' \
-H 'X-API-Key: YOUR_API_KEY'
# { "storageType": "local", "count": 150, "sizeBytes": 15728640, "sizeMB": "15.00" }

# 2. Export all files. The archive is written under data/ (it survives the restart) and the
# response gives you its path.
curl -s 'http://localhost:2785/api/infra/storage/export' \
-H 'X-API-Key: YOUR_API_KEY'
# { "message": "Storage export completed",
# "download": "data/exports/storage-export-1750000000000-<uuid>.tar.gz" }
# The path is relative to the server's working directory, not absolute.

# 3. Switch storage in .env. The credentials are REQUIRED either way: nothing fills them
# in for you, and MinIO itself refuses to start with empty root credentials (it reads
# the same two variables). MINIO_BUILTIN is not forwarded by the bundled compose files,
# so under Compose the --profile minio flag in step 4 is what starts the bundled MinIO.
# STORAGE_TYPE=s3
# S3_ACCESS_KEY_ID=<choose one>
# S3_SECRET_ACCESS_KEY=<choose one>
# S3_BUCKET=openwa
# S3_ENDPOINT=http://minio:9000 # bundled MinIO or any S3-compatible store; leave
# # unset for AWS S3, which derives its own endpoint

# 4. Restart. The bundled MinIO sits behind a compose profile, so a plain
# `docker compose up -d` would leave it out and storage would stay on local disk.
docker compose --profile minio up -d

# 5. Import the archive into the new storage (use the path from step 2)
curl -s -X POST 'http://localhost:2785/api/infra/storage/import' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"filePath": "/app/data/exports/storage-export-1750000000000-<uuid>.tar.gz"}'
# { "imported": true, "count": 150, "failed": 0, "storageType": "s3" }

Three constraints to plan around:

  • filePath must point inside the data/ directory. The import rejects any path outside it with 400 Bad Request — a path-traversal guard. Keep the archive where storage/export wrote it.
  • The archive is deleted STORAGE_EXPORT_TTL_MS (default 1 hour) after the export while the process keeps running. The restart in step 4 cancels that timer, and the next boot removes archives older than STORAGE_EXPORT_SWEEP_MAX_AGE_MS (default 24 hours). Import it soon after the restart, or re-export.
  • A corrupt or truncated archive returns 400 Bad Request with the underlying reason (gzip error, read failure, or a breached size/entry cap). Since v0.11.0 these failures fail the request cleanly — previously a corrupt gzip could take the server down mid-import.
  • storage/import copies into the active backend without deleting the source files. On S3 the store still reads STORAGE_LOCAL_PATH (default /app/data/media in the container) as a fallback: what is left there is listed, counted, served when the bucket has no copy, and archived by scripts/backup.sh. Media written between the export and the restart, and any file whose import failed, live there alone, so never empty it outright. Once the import answers "failed": 0, stop the sessions and run steps 2 and 5 again: on S3 the export reads the local directory too, so this copies what only it held into the bucket. When that import also answers "failed": 0, move the directory's contents aside (keep the directory: writes land there while the bucket is down), or delete only the local files whose key the bucket already holds.

Switch Redis (cache and queue)​

Redis backs the rate-limit counters, the cache connection and cross-replica WebSocket event fan-out (REDIS_ENABLED=true), and the BullMQ job queue (QUEUE_ENABLED=true). Cache data is ephemeral and rebuilds from the database on demand, so there is no migration endpoint — point at the new instance and restart.

# In .env:
REDIS_ENABLED=true
REDIS_BUILTIN=false # external Redis
REDIS_HOST=your-redis-host
REDIS_PORT=6379
REDIS_PASSWORD=optional

The built-in Redis serves plain TCP and only its default user, so with REDIS_BUILTIN=true, the bundled host and Redis, the queue or the cache on, a boot refuses REDIS_TLS=true or a REDIS_USERNAME other than default (v0.26.0+). A managed Redis that needs TLS or a named user is an external one: set REDIS_BUILTIN=false and its REDIS_HOST. Deployments that share one Redis each need their own QUEUE_PREFIX (v0.26.0+, default bull); it scopes the BullMQ queues only, not the rate-limit counters or the WebSocket fan-out (see Horizontal scaling).

With QUEUE_ENABLED=true the queue is the part that needs care: switching Redis can strand jobs that are mid-flight.

Drain the queue before switching Redis

With QUEUE_ENABLED=true, two queues live in Redis: webhook-queue (outbound webhook deliveries) and ingress-queue (inbound integration events). Before you change REDIS_HOST and restart, wait until both are empty so in-flight jobs aren't lost. Read pending job counts from the Bull Board dashboard at /api/admin/queues (an admin key that is not restricted to specific sessions or, since v0.23.6, to selected chats) — it shows the live depth of both queues. When neither reports a waiting or active job, it's safe to switch. A queue is named by its Redis key prefix and its name, so the same holds for changing QUEUE_PREFIX (v0.26.0+): jobs queued under the old prefix are left unprocessed. Turning QUEUE_ENABLED off needs the same drain: with the queue off, a pending webhook outbox row is replayed inline whatever Redis still holds, and so is a pending ingress row, which since v0.31.0 is also the state of a delivery whose job is queued, so a job left in webhook-queue or ingress-queue runs again when the queue is turned back on and the same event is delivered twice.

Forcing the board's obliterate action deletes jobs that are still active

The Bull Board UI's obliterate action requires the queue to be paused first, and since v0.23.3 (Bull Board 9) it offers a force option for getting past jobs that are still active. Forcing it deletes those active jobs too. Bull Board 8 refused the obliterate outright while jobs were active. Drain the queue as described above instead. The route stays admin-only, behind the same ADMIN key check as the rest of /api/admin/queues.

GET /api/infra/status covers only the webhook queue

The response carries a single queue.webhooks block, read live from webhook-queue, where pending is waiting plus active plus delayed. There is no block for ingress-queue, and the counts fall back to { pending: 0, completed: 0, failed: 0 } when the queue is disabled or Redis is unreachable, so a zero there is not by itself proof the queues are drained. Read /api/admin/queues for the ingress queue and to tell a real zero from a degraded one.

Move sessions to a new host​

A session's auth is engine-specific credential data tied to one host's data directory. To move sessions, carry a scripts/backup.sh archive to the new host and restore it there. The archive holds the auth directories of both engines, both databases (so the API keys and the audit log move too, which the data export does not carry) and the plaintext admin key, and the restored sessions reconnect against the copied credentials, with no fresh QR scan.

Step 1, on the old host: stop each session (POST /api/sessions/{sessionId}/stop) so the auth files are not mid-write, then take the backup as in Take a backup. The archive lands in ./backups.

Step 2, on the new host: check out the same release and create the folder the archive goes to:

# 2. On the new host
git clone --branch v<release> https://github.com/rmyndharis/OpenWA.git /path/to/OpenWA \
&& mkdir -p /path/to/OpenWA/backups

Step 3, back on the old host: copy the archive and your .env to the new host. rsync copies between this host and one remote host, never between two remote hosts, so run it where the files are:

# 3. On the old host
rsync -av --progress ./backups/openwa-backup-YYYYMMDD-HHMMSS.tar.gz new-host:/path/to/OpenWA/backups/
rsync -av .env new-host:/path/to/OpenWA/

Step 4, on the new host in that checkout: build the image and restore into the new volume. A fresh volume holds no live database, so no --force is needed, and the chain stops at the first command that fails:

# 4. On the new host, in /path/to/OpenWA
docker compose build openwa-api \
&& docker compose run --rm --no-deps --entrypoint /app/scripts/restore.sh \
-v "$PWD/backups:/backups" -e OPENWA_RESTORE_SNAPSHOT_DIR=/backups -e TMPDIR=/backups -e HOME=/tmp \
openwa-api /backups/openwa-backup-YYYYMMDD-HHMMSS.tar.gz

Continue only when the script's last line starts with [restore] Restore complete.. On PostgreSQL the archive carries a pg_dump (database.sql): load it into an empty database now, with the gateway still down, using the PostgreSQL block of Roll back a bad migration (step 3). The gateway must not start until the dump is loaded, because it would migrate a fresh database first and the rename in that block fails on its open connections. An archive that holds the SQLite data store is refused while DATABASE_TYPE is postgres (v0.31.0+), so on a new host whose .env selects PostgreSQL the restore stops before it writes anything: see Take a backup.

# 5. Start the new host (bundled PostgreSQL: docker compose --profile postgres up -d)
docker compose up -d

# 6. Start each session, then check that it reconnected without a QR prompt. Sessions come back on
# their own only with AUTO_START_SESSIONS=true (the boot log says how many it left down, as
# action=auto_start_disabled, since v0.30.3), and one stopped before the backup stays stopped
# until this start. The restored main database brings the old host's API keys with it
curl -s -X POST 'http://localhost:2785/api/sessions/{sessionId}/start' -H 'X-API-Key: YOUR_API_KEY'
curl -s 'http://localhost:2785/api/sessions' -H 'X-API-Key: YOUR_API_KEY'

Once started, the session re-initializes against the copied auth and reconnects. If the auth was truncated or corrupted in transit, the session fails to connect — re-scan the QR code for it to recover. Since v0.23.3 a session that was linked before and comes back to the QR stage logs a relink_required warning, so the server log names the problem instead of leaving you to infer it from the QR. See Sessions for the connection lifecycle.

Roll back a bad migration​

If an upgrade or data move goes wrong, restore the backups you took. Rolling back is the reverse of the upgrade: stop, restore databases + auth from the archive, revert the schema when that archive was taken after the upgrade, move the code back to the previous release, restore config, start, verify. The commands are for Docker Compose; the Kubernetes variant follows the blocks.

# 1. Stop the new version
docker compose down

# 2. Restore the databases, engine auth, local media, plugins and bootstrap config from the archive
# that "Take a backup" copied into ./backups. The script runs in the image, against the data
# volume. --force is needed because the databases in place still hold the failed upgrade's data;
# that state is kept in ./backups/data.pre-restore-<timestamp>, the path the script prints.
# OPENWA_RESTORE_SNAPSHOT_DIR must name a directory OUTSIDE the data directory: the snapshot
# copies the whole data directory and cannot be written into it. TMPDIR keeps the extracted
# archive off the container's memory-backed /tmp, and HOME moves off /app/data, which the script
# refuses as a data directory
docker compose run --rm --no-deps --entrypoint /app/scripts/restore.sh \
-v "$PWD/backups:/backups" -e OPENWA_RESTORE_SNAPSHOT_DIR=/backups -e TMPDIR=/backups -e HOME=/tmp \
openwa-api /backups/openwa-backup-YYYYMMDD-HHMMSS.tar.gz --force
# The archive holds both engine directories, and a rollback past v0.23.5 needs both, on either
# engine: its first boot renames each session's auth directory from the session name to the
# session id and keeps nothing behind, so an older image finds no directory and starts every
# session at a QR code. The backup must PREDATE the
# first start on v0.23.5; one taken after the upgrade does not qualify. The same holds for a
# rollback that crosses a browser major: every amd64 rollback past v0.23.5 does (Chrome for
# Testing 146 to 153), and so does an amd64 rollback from v0.26.0 to v0.25.0 or earlier (153
# to 156), from v0.29.0 through v0.30.3 to v0.28.0 or earlier (156 to 157), or from v0.31.0 to
# v0.30.3 or earlier (157 to 158), whose backup must predate the first start on the newer image
# (from v0.31.0 to v0.28.0 or earlier, the first start on v0.29.0 or later). An arm64 one can, since that
# image runs whatever chromium Debian
# shipped when it was built. An older Chrome deletes the IndexedDB a newer one opened, which is
# where whatsapp-web.js keeps the WhatsApp login. A session first paired on v0.23.5, on
# v0.26.0, on v0.29.0 through v0.30.3, or on v0.31.0 for a rollback from it is in no such backup and must be paired again.

Continue only when the script's last line starts with [restore] Restore complete.. An unedited archive name prints the usage line and restores nothing, and moving the code back onto unrestored data is the state this rollback exists to prevent. An archive that holds the SQLite data store, as a backup taken before a move to PostgreSQL does, is refused with exit 1 while DATABASE_TYPE is postgres (v0.31.0+): change DATABASE_TYPE and DATABASE_NAME where they are set, as Take a backup says, and run it again.

PostgreSQL data store only. Step 2 leaves the upgraded database in place, and the dump cannot be replayed over it: its CREATE statements fail and its rows mix with the existing ones. Load it into an empty database instead. Start only the database, because openwa-api must stay stopped (the rename fails on its open connections). The upgraded database is kept under a new name and an empty one takes its place. POSTGRES_USER and POSTGRES_DB are the container's own variables, the role and database the app uses, and the sed drops a line that the image's pg_dump 17 writes and PostgreSQL 16 rejects. A database container created from the dashboard's Infrastructure page is started with docker start openwa-postgres: replace the second link of the chain with that. The chain stops at the first command that fails, the archive check included:

# 3. Load the PostgreSQL dump into an empty database
tar -tzf ./backups/openwa-backup-YYYYMMDD-HHMMSS.tar.gz ./database.sql >/dev/null \
&& docker compose --profile postgres up -d postgres \
&& docker exec openwa-postgres sh -c 'until pg_isready -q -U "$POSTGRES_USER"; do sleep 1; done' \
&& docker exec openwa-postgres sh -c 'psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d postgres \
-c "ALTER DATABASE \"$POSTGRES_DB\" RENAME TO \"${POSTGRES_DB}_pre_restore_$(date +%Y%m%d%H%M%S)\"" \
-c "CREATE DATABASE \"$POSTGRES_DB\" OWNER \"$POSTGRES_USER\""' \
&& tar -xzOf ./backups/openwa-backup-YYYYMMDD-HHMMSS.tar.gz ./database.sql | sed '/^SET transaction_timeout = 0;$/d' |
docker exec -i openwa-postgres sh -c 'psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d "$POSTGRES_DB"'
Archive taken after the upgrade: revert the schema before step 4

Before step 4, check which archive step 2 restored. If it was taken before the upgrade, it already holds the old schema, and a revert on top of it undoes migrations the older release needs: skip this box and go straight to step 4. If it was taken after the first start on the newer release, its schema is already migrated: run the reverts below now, with the image you just ran, because step 4 replaces that image with one built from the older code, which does not hold the revert code. On PostgreSQL the database from step 3 must be up.

Each migration:revert:prod undoes exactly one migration, so the count is fixed by the pair of releases. Rolling back from v0.25.0 to v0.24.0 is five data-database reverts and no main-database revert, because both releases ship the same three main migrations. List the executed migrations first. The last five must be AddWebhookDeliveryFailurePayload, AddSendIdempotencyKeys, DeduplicateTerminalWebhookFailures, AddMessageWindowIndexes and AddIntegrationDeliveryFailureDeliveryIndex:

docker compose run --rm openwa-api npm run migration:show:prod

If the list does not end with those five, stop: run no revert and restore a pre-upgrade backup instead. Otherwise run the five reverts, and no more:

for i in 1 2 3 4 5; do docker compose run --rm openwa-api npm run migration:revert:prod || break; done

They drop the send_idempotency_keys table and the payload column of webhook_delivery_failures, with what those hold, and the indexes v0.25.0 added; the duplicate terminal failure rows the upgrade removed do not come back. A sixth revert is not part of this rollback: it removes v0.24.0's own migrations from the ledger, so v0.24.0 would list the first of them as pending again.

Rolling back from v0.26.0 to v0.25.0 is four data-database reverts and no main-database revert, again because both releases ship the same three main migrations. Check the list the same way: the last four must be AddWebhookOutboxSessionIndex, BackfillLegacyMessageTypes, AddLidMappingReportSource and RepairSqliteMessageFts. If it does not end with those four, run no revert and restore a pre-upgrade backup instead. Otherwise run the four reverts, and no more:

for i in 1 2 3 4; do docker compose run --rm openwa-api npm run migration:revert:prod || break; done

They drop IDX_webhook_outbox_events_sessionId and the isReported column of lid_mappings, and clear the phone and session of every mapping no engine has reported, so that an older reader cannot authorize it. The legacy message-type conversion and the full-text index repair are not undone. A fifth revert is not part of this rollback: it removes v0.25.0's own AddIntegrationDeliveryFailureDeliveryIndex from the ledger, so v0.25.0 would list it as pending again.

Rolling back between v0.31.0, v0.30.3, v0.30.2, v0.30.1, v0.30.0, v0.29.1, v0.29.0, and v0.28.0 requires no schema revert: all eight releases share the same data and main migration chains (ending at AddStatusMediaPathIndex on the data database). So does rolling back between v0.27.1 and v0.27.0, whose data chain ends one migration earlier, at AddChatStateDeletedAt. Rolling back from v0.28.0 or later to v0.27.1 or v0.27.0 needs no revert either: one migration:revert:prod run in the newer image would only drop IDX_status_updates_mediaPath (it undoes AddStatusMediaPathIndex and nothing else). A later revert, for example on the way to v0.26.0, then has to run in an image of v0.28.0 or later, because the older image does not know the newest ledger entry and stops with No migration <name> was found in the source code.

Rolling back from v0.27.0 (or any later release through v0.31.0) to v0.26.0 undoes AddChatStateDeletedAt, which drops chat_states.deletedAt, and needs no main-database revert. Each migration:revert:prod undoes only the newest data migration, so the number of runs depends on the release you roll back from: one from v0.27.0 or v0.27.1, two from v0.28.0 or later, because v0.28.0 added AddStatusMediaPathIndex after it. Run npm run migration:show:prod first, then docker compose run --rm openwa-api npm run migration:revert:prod, and show the list again after each run: stop as soon as AddChatStateDeletedAt1791700000000 is listed as pending, and run no more.

Every revert reports success, later ones drop columns and tables that hold data, the oldest data migration drops sessions, messages, webhooks and message_batches, and the oldest main migration drops api_keys and audit_logs. For any other rollback target, restore a pre-upgrade backup and run no schema revert.

If a revert stops with No migration <name> was found in the source code, the image was already rebuilt from the older code, so step 4 has run. That failed revert changed nothing. Run docker compose down, check out the release you rolled back from again (git checkout v<current-version>; if git refuses because step 4 restored docker-compose.yml, run git checkout -- docker-compose.yml first, your copy stays in ./backups) and rebuild with docker compose build openwa-api. Then run the reverts above and repeat step 4.

For every data store, move the code back, restore the config over the checkout and start. The checkout comes first: docker-compose.yml is tracked, so a copy restored over it before the checkout makes git refuse to switch onto a tag where that file differs. The repo's compose file builds the image from source; a deployment pinned to a published image bumps the tag in its compose file and runs docker compose pull in place of --build. It is one chain, and a shell rejects an unedited placeholder, so nothing in it runs until the tag is filled in:

# 4. Move the code back, restore config over the checkout, start it
git checkout v<previous-version> \
&& cp ./backups/.env ./backups/docker-compose.yml . \
&& docker compose up -d --build

# 5. Verify
curl -f http://localhost:2785/api/health

The script restores everything the archive holds, local media and plugins included, so files written after the backup are replaced by the archive's copies; the snapshot in ./backups keeps what you restored over. The snapshot copies the whole data directory, archives still kept under /app/data/backups included, so allow free space for those as well. With an external PostgreSQL server, rename the upgraded database and create an empty one under the DATABASE_NAME the app uses in the same way, then load the dump into it: restore.sh stages database.sql in the data directory and prints the psql command, with the TLS mode your DATABASE_SSL implies, and DATABASE_URL in it is your own connection URL for that database, not an OpenWA setting. On Kubernetes, scale the StatefulSet to zero and run restore.sh from a helper pod on the same PVC, using the release's image, with OPENWA_RESTORE_SNAPSHOT_DIR and TMPDIR on a writable emptyDir such as /restore; the tagged restore runbook has the pod spec and the copy-off steps.

Rolling back from v0.31.0 to v0.30.3 or earlier

On linux/amd64, v0.31.0 upgrades Chrome for Testing from 157 to 158 (158.0.8127.36), and a source install that runs the Chrome Puppeteer downloads (no PUPPETEER_EXECUTABLE_PATH) moves from Chrome 156 to 157 with Puppeteer 25.17.0. Rolling back to v0.30.3 or earlier without restoring sessions/ from a backup taken before the first start on v0.31.0 causes the older Chrome to clear the profile's IndexedDB and start every whatsapp-web.js session at a QR code, and a session first paired on v0.31.0 must be paired again. An amd64 rollback to v0.28.0 or earlier needs a backup taken before the first start on v0.29.0 or later instead, as the next box says. Baileys sessions are unaffected. The linux/arm64 image runs the chromium Debian ships when it is built, whose major can differ between releases.

Rolling back from v0.29.0 through v0.31.0 to v0.28.0 or earlier

On linux/amd64, v0.29.0 upgrades Chrome for Testing from 156 to 157 (157.0.8103.38 in v0.29.0 and v0.29.1, 157.0.8103.50 in v0.30.0, 157.0.8103.78 in v0.30.1 through v0.30.3), and v0.31.0 moves it on to 158. Rolling back to v0.28.0 or earlier without restoring sessions/ from a backup taken before the first start on v0.29.0 or later causes Chrome 156 to clear the profile's IndexedDB and start every whatsapp-web.js session at a QR code. Baileys sessions are unaffected, and a linux/arm64 rollback can cross a browser major too, since that image runs the chromium Debian shipped when it was built. Rolling back from v0.28.0 or later to v0.27.1 or earlier also drops GET /api/sessions/{sessionId}/messages/{chatId}/{messageId}/receipts, and rolling back from v0.27.1 or later to v0.27.0 drops GET /api/sessions/{sessionId}/contacts/{number}/lid.

Rolling back from v0.27.0 to v0.26.0

Revert AddChatStateDeletedAt before moving the image back to v0.26.0 when keeping a post-upgrade data database, running migration:revert:prod until migration:show:prod lists it as pending (from v0.28.0 or later that takes two runs, AddStatusMediaPathIndex first), or restore a pre-upgrade backup. v0.26.0 does not read SEARCH_CONTAINS_ENABLED or the match query parameter on GET /api/search, does not expose PUT /api/sessions/{sessionId}/groups/{groupId}/member-label, and passes PostgreSQL session parameters as startup packet options rather than per-connection SQL statements.

Rolling back from v0.25.0 to v0.24.0

v0.24.0 never replays webhook outbox rows in state queued and prunes them after WEBHOOK_OUTBOX_RETENTION_DAYS (default 7). Drain or explicitly accept the loss of those rows before a rollback. The upgrade also removes duplicate terminal webhook_delivery_failures rows; reverting the version does not restore them. Restore a pre-upgrade database when those copies are required.

Rolling back from v0.26.0 to v0.25.0

The amd64 image runs Chrome for Testing 153 on v0.25.0 and 156 on v0.26.0, so the restore in step 2 must come from a backup taken before the first start on v0.26.0, or every whatsapp-web.js session starts at a QR code. v0.25.0 does not read QUEUE_PREFIX: its queues use the default bull prefix, so with QUEUE_ENABLED=true jobs queued under a custom prefix stay unprocessed in Redis. It does not read the deleting and deleting-stopped records that a delete leaves on a session either, so its takeover sweep can adopt a session whose delete failed part-way. Reverting AddLidMappingReportSource clears the unreported phone mappings; restore a pre-upgrade database when those must be kept.

Rolling back past v0.23.6 lifts chat scopes

An earlier release does not know allowedChats, so a key restricted to selected chats reaches every chat on its sessions there. Restoring the pre-upgrade main.sqlite, as step 2 does, returns every key to the scope it had before the upgrade and removes keys created since. If you roll back without restoring it, revoke the chat-scoped keys first. With an older main database on its default synchronize, the older release also drops the allowedChats column, so the restriction stays gone after you upgrade again and has to be set anew with PUT /api/auth/api-keys/{id}.

Common migration issues​

ProblemLikely causeFix
403 Forbidden on an /api/infra/* callAPI key lacks the ADMIN role, or is restricted to specific sessions or (v0.23.6+) to selected chatsUse an admin key with no session or chat restriction. See Authentication.
import-data wiped data you wanted to keepImport replaces, it does not mergeRestore from backup; only import into a fresh target.
Boot fails with PostgreSQL data connection is not on UTC (v0.23.6+)A pooler drops the connection's SET TIME ZONE 'UTC', or a server-side default overrides itALTER DATABASE "<database>" SET TimeZone='UTC', or let the statement through the pooler.
Timestamps read hours off after upgrading to v0.23.6PostgreSQL data written by a gateway, or a database server, that ran outside UTC, and not converted before the first startFollow PostgreSQL deployments that ran outside UTC for a database v0.23.6 has already written to: the rows v0.23.6 wrote are already UTC, and the full conversion would shift them too.
import-data returns 409 ConflictThe code in the body says why: IMPORT_WOULD_ORPHAN_ENGINES (the restore would orphan an engine running for a session the backup lacks), IMPORT_ALREADY_RUNNING or EXPORT_IN_PROGRESS (another import or a data export is running), or IMPORT_NESTED_TRANSACTION (another transaction holds the SQLite connection)For the orphan case, stop the listed sessions first, retry with stopOrphans: true (preferred), or force: true and restart promptly. For the others, wait and retry with nothing else running.
import-data returns 413The file is larger than the target's BODY_SIZE_LIMIT (25mb by default)Raise BODY_SIZE_LIMIT in .env to at least the file size, keep an explicit INFLIGHT_BODY_BUDGET_BYTES at twice that or more, restart, import again, then set it back.
storage/import returns 400 Bad RequestfilePath is outside data/, the archive was already removed (by the one-hour timer, or by a boot sweep once it was 24 hours old), or the archive is corruptUse the path storage/export returned, import soon after the restart, and re-export a removed or damaged archive.
Session won't reconnect after a moveAuth data truncated or corrupted in transitRe-scan the QR code for that session.
Permission denied on the data directoryThe container was started as a non-root user (--user, or user: in Compose) that cannot write the bind-mounted directory; a default root start re-owns /app/data itselfSee Fix file ownership on bind mounts.
Migration command errors on the prod imageRan a non-:prod script (needs the TS toolchain)Use migration:run:prod (and :main:prod for the auth/audit DB).
The port stays closed for minutes after upgrading to v0.26.0, or the Helm pod restarts during bootThe one-time legacy message-type conversion (about a minute per million legacy rows on PostgreSQL, inside the boot transaction), the new index builds, and on SQLite the full-text index check and rebuildRun migration:run:prod first, or raise startupProbe.failureThreshold. See Run schema migrations.
restore.sh stops naming a key such as SESSION_DATA_PATH (v0.26.0+)A path from the archive's own .env.generated leaves the data directory, passes through a link that does not resolve, or lies inside or around a directory the restore refills. Nothing was restoredSet that key in the environment or ./.env to restore there.
restore.sh exits 1 and restores nothing, naming DATABASE_TYPE (v0.31.0+)The archive holds the SQLite data store (openwa.sqlite) while DATABASE_TYPE resolves to postgres, from the environment, ./.env or the .env.generated the restore reads (the archive's copy when it carries one, else the data directory's)Change DATABASE_TYPE and DATABASE_NAME where they are set (an environment value, such as a Compose environment: entry or a Helm ConfigMap, outranks ./.env, which outranks .env.generated) and run it again. To move a SQLite install to PostgreSQL, restore into a SQLite install, then export, switch and import. See Take a backup.
A whatsapp-web.js session ends failed after upgrading to v0.31.0, and its start answers 504whatsapp-web.js 1.34.8 ends its wait for the page's connection to WhatsApp after WWEBJS_AUTH_TIMEOUT_MS (30000 ms unless set), where 1.34.7 waited with no limit, and this host takes longer. AUTO_START_SESSIONS does not start a failed session at bootRaise WWEBJS_AUTH_TIMEOUT_MS (for example 120000), apply it (under Compose, docker compose up -d recreates the container with the new .env value), then start the session with POST /api/sessions/{sessionId}/start.
Every whatsapp-web.js session starts at a QR code after a rollbackThe rollback crossed a browser major (on amd64, v0.31.0 to v0.30.3 or earlier, v0.29.0 through v0.30.3 to v0.28.0 or earlier, v0.26.0 to v0.25.0 or earlier, or v0.23.5 or later to v0.23.4 or earlier; on a source install that runs Puppeteer's Chrome, v0.31.0 to v0.30.3 or earlier) without restoring sessions/ from a backup taken before the first start on the newer image (on amd64, from v0.31.0 to v0.28.0 or earlier, before the first start on v0.29.0 or later)Restore sessions/ from such a backup; a session first paired on the newer image must be paired again. See Roll back a bad migration.
DELETE /api/sessions/{sessionId} times out, or answers 409 or 503 (v0.26.0+)A large history is removed in batches, and a client or proxy timeout cut the request short. 409: another node owns the session or took it over mid-delete, and earlier batches may be committed. 503 on SQLite: another transaction stayed open for 10 s; since v0.28.0 also when the database cannot check or claim session ownership. Since v0.31.0 a 503 also when the database does not answer the read of the session the delete makes once it holds its claim (it answered 500 before)Repeat DELETE to finish, or POST /api/sessions/{sessionId}/start to keep the session. Size client and proxy timeouts for large histories.
Boot or migration CLI fails with Cannot read <path>: <reason> (v0.28.0+).env or data/.env.generated exists on disk as a directory or cannot be read by the runtime userMake the file readable by uid 997 (or the user running the CLI), replace the directory with the file, or run the migration CLI inside the image.
import-data returns imported: false naming a session id or a JSON column before touching the database (v0.28.0+)The archive contains a session id outside 1..128 ASCII letters, digits, and hyphens, or a malformed JSON columnFix the named row in the archive and re-run the import; nothing in the target database was cleared.

Next steps​

  • Deployment — production setup, profiles, and health checks.
  • Horizontal Scaling — what can be shared across instances and how to grow one deployment.
  • Troubleshooting — diagnosing reconnection and config problems.