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.
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.
- 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 theADMINrole — a read/send key returns403. See Authentication. - Shell access to the host (or container) and roughly twice your current data size in free disk.
- Every
docker composecommand below targets the repository's defaultdocker-compose.yml. If you run the single-containerdocker compose -f docker-compose.dev.yml up -dstack instead, add-f docker-compose.dev.ymlto each of them and writeopenwawherever a command names theopenwa-apiservice.docker execanddocker cpname the container instead, which isopenwa-apiin both files, so keep that name there. Do not carry the flag onto the--profile postgrescommands: those services exist only in the production file. The two files also store data differently: a bind-mounted./dataon the host versus the named volumeopenwa_openwa-data, which has no./datadirectory on the host. Mixing them points the stack at the wrong data, and a host path such as./data/sessionsexists only for the bind-mounted stack. A standalone Compose file such as the Traefik or Cloudflare Tunnel example on the Deployment page names its serviceopenwaand sets no container name: writeopenwafor the service, and indocker execanddocker cpuse the container name thatdocker compose psshows, or addcontainer_name: openwa-apito that service. - This page targets OpenWA v0.31.0. Confirm your running version with
GET /api/healthand 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.sharchive, which holdsmain.sqliteand the data store (openwa.sqlite, or apg_dumpon PostgreSQL). - Session auth backed up — both
sessions/(whatsapp-web.js) andbaileys/(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
.envanddocker-compose.yml. - Current version recorded with
GET /api/healthand your API key (theversionfield 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
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/andbaileys/) before starting the new version. v0.31.0 adds no database schema migrations. Onlinux/amd64the image moves Chrome for Testing from 157 to 158 (158.0.8127.36, from157.0.8103.78in v0.30.1 through v0.30.3), and a source install that runs the Chrome Puppeteer downloads (noPUPPETEER_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 storedwhatsapp-web.jslogins unlesssessions/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 upSESSION_DATA_PATH(defaultdata/sessions/) before the first start and restore it before downgrading. Thelinux/arm64image 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 answers504), and a session that endsfailedis not started again at boot byAUTO_START_SESSIONS. RaiseWWEBJS_AUTH_TIMEOUT_MSthere, then start the session. scripts/restore.shexits1before it writes anything when the archive holds the SQLite data store andDATABASE_TYPEispostgres, where v0.30.3 exited0after writing a file the app never reads. A rollback to a SQLite backup taken before a move to PostgreSQL meets this: changeDATABASE_TYPEandDATABASE_NAMEwhere they are set, then run it again (see Take a backup).- The local media store (
STORAGE_LOCAL_PATH,./data/mediaby default) is owner-only: the gateway sets its root0700at every boot, whateverSTORAGE_TYPEis, 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 files0700and0600. The storage export archive is written0600in a0700data/exports, where it was0644in0755, 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 asopenwa). Files written earlier keep their mode but sit under the0700root. WithSTORAGE_TYPE=s3the 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 fromRELEASE.2026-09-16toRELEASE.2026-11-12, a security release. An existingopenwa-miniocontainer keeps the image it was created from until it is recreated. With the Composeminioprofile, rundocker compose --profile minio pull minio && docker compose --profile minio up -d minio. For a container the dashboard created, rundocker 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). Theopenwa_minio-datavolume and its media are kept either way. - With the queue on (
QUEUE_ENABLED=true), an ingress event row stayspending, with its payload, until the worker settles it, where it was markeddispatchedwith 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 iningress-queueorwebhook-queueruns 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 address192.88.99.2, as it already refused198.18.0.0/15: a webhook, media or plugin url that points into one is refused, and a receiver on such an address needsSSRF_ALLOWED_HOSTS. - With
STORE_EPHEMERAL_MESSAGES=false(the default istrue), Baileys no longer keeps an incoming message of a disappearing-messages chat: no copy inbaileys_stored_messages(where it stayed, and in backups), no text as the chat'slastMessage, 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 attrueif consumers act on messages of disappearing chats. Rows stored before the upgrade stay untilBAILEYS_MESSAGE_STORE_LIMITevicts them. - A
whatsapp-web.jsunblock (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 onwhatsapp-web.jsalso answer400for a number that WhatsApp, asked for it, holds no privacy id for. - Baileys lists
nameas""for a chat held under a privacy id that has no saved, verified or push name, with itsphonewhen the session maps the id, where v0.30.3 listed the id's own digits: title such a chat byphone, else byid. This reachesGET /api/sessions/{sessionId}/chats, the MCPSessionGetChatstool and a plugin'sgetChats. Every Baileys chatnameis 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
MessageListcall that does not setinlineMediareturns 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. PassinlineMedia: trueto get the bytes.GET /api/sessions/{sessionId}/messagesstill inlines by default. - The retryable
409awhatsapp-web.jssession 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 carriescodeENGINE_PAGE_RELOADINGandretryAfterSeconds(5). A client that matched the old text,Retry in a few seconds., must match thecode. A send, reply or forward whose first attempt had already run when the page reloaded answers a409with nocodethat 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
ingressthat is not a list, an hmac-sha256contentTemplatethat is not a string, or aheader,timestampHeader(hmac-sha256 and shared-secret routes),dedupHeaderorconversationId.headerthat is not a string fails to load at boot (statuserror, 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 answers400naming the field. - A plugin
ctx.storagekey that holds a lone UTF-16 surrogate (half of an emoji left byslice) is refused:setanddeletereject it as an unsafe key andgetanswersnull. A record an earlier version wrote under one stays reachable through the key spelled withU+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/amd64their images run Chrome for Testing157.0.8103.78, where v0.30.0 ran157.0.8103.50, the same major. - Baileys reports poll votes as
poll.vote, aswhatsapp-web.jsalready 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 enginespoll.votecarries at most 32selectedOptionsof 1024 characters each and apollNameof 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 anunknownmessage, 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 emptyunknownmessage 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 withStream Errored (ack). v0.30.2 also decodes it, so those statuses reach the status list and thestatus.receivedwebhook, and a status that fails to decrypt is dropped, not retried. Both come from the install-time patchscripts/patch-baileys-status-ack.js. - The session config key
linkPreview(v0.30.3+, set withPATCH /api/sessions/{sessionId}/config) is the default for asend-textorsend-templatethat sets neitherlinkPreviewnorcustomLinkPreview: a value in the request wins,falsesends without a preview on both engines, andnullreturns to the engine's default. - A
message:sendingplugin that rewrites asend-textto carry bothlinkPreview: falseandcustomLinkPreviewnow gets the400the same request gets directly (v0.30.3+); Baileys sent it with the supplied preview. PATCH /api/sessions/{sessionId}/configon 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/andbaileys/) 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. Onlinux/amd64the v0.29.0 through v0.30.3 images move Chrome for Testing from 156 to 157 (157.0.8103.38in v0.29.0 and v0.29.1,157.0.8103.50in v0.30.0,157.0.8103.78in 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 storedwhatsapp-web.jslogins unlesssessions/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 fromwppconnect-team/wa-versionbefore 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 asweb_version_html_rejected), stepping back up to 3 older settled builds onauto/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, awhatsapp-web.jssession configured with a credentialedhttp://orhttps://proxyUrlbypasses WhatsApp Web's service worker so in-pagefetch()media downloads authenticate through the proxy instead of failing with407. - In v0.29.1+,
message.receivedandmessage.sent(webhooks and WebSocket) on both engines, and live chat history (GET /api/sessions/{sessionId}/messages/{chatId}/history,whatsapp-web.jsonly), includeisForwarded: trueand (when positive)forwardingScoreon 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 dispatchessession.restriction) when WhatsApp requests a passkey during linking, logsbaileys_link_restarton post-link515restarts andstage+aliveMsonbaileys_connection_dropped(endinglastErroron a reconnect-looping session with the stage from the 5th attempt), and appliespatch-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 withTypeError: terminated. Also in v0.30.0+, MCP tool schemas setadditionalProperties: falseand refuse unknown arguments or payloads over 10,000 array items and object keys,MessageListaddsinlineMediaand the REST list filters,MessageSearchaddstype, all 11 MCP send tools acceptidempotencyKey,MessageSendTemplateacceptslinkPreview,SessionGetPresencereturnsobservedAtas an ISO date-time string,GroupFindAllreturns404for an unknown session, and the inline MCP text threshold rises from 4 KiB to 32 KiB. - Boot and the migration CLI (
npm run migration:runandmigration:run:prod) now fail fast, naming the file (Cannot read <path>: <reason>), when.envordata/.env.generatedexists 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_KEYset no longer prints the key in the startup banner, later boots print no prefix of it, andGET /api/auth/api-keyslists 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..128ASCII 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 withimported: falseandwarningswithout clearing the target tables. It also clears inherited secrets on disabled or non-wildcard (sessionIds)plugin_instancesrows unless an existing instance row matches the sameid,pluginId, andconfigorigin.scripts/restore.sh(v0.28.0+) extracts archives withtar -Pand 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); aPOST /api/sessionsconfigover 16,384 bytes serialized (400); a webhook write with more than 27eventsor a webhook or automation rule id filter value over 128 characters (400);GET /api/sessions/{sessionId}/contacts/check/{number}(and MCPopenwa_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 returned403or404);POST /api/sessions/{sessionId}/messages/send-stickeronwhatsapp-web.jswith non-image/non-video media (400);POST /api/sessions/{sessionId}/chats/pinor.../chats/muteon Baileys for an unpaired 1:1 chat (400);POST /api/sessions/{sessionId}/messages/editon Baileys when the target message has no text or caption (403, matchingwhatsapp-web.js); andPOST /api/sessions/{sessionId}/channels/{channelId}/owner/transferor.../admins/demotewhen{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 answer404(not400) 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 astype: "unknown"onmessage.received,message.sent, ormessage.ack. On Baileys (v0.28.0+),message.acknow reportsdeliveredandreadfor 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 falsemessage.revoked. PUT /api/plugins/{id}/configon a built-in engine plugin (whatsapp-web.jsorbaileys) deep-merges nested plain objects (puppeteer,baileys) into the stored config instead of replacing them, clears a key at any depth when set tonull, and falls back toPUPPETEER_HEADLESSandPUPPETEER_ARGSfrom the environment for keys omitted from a partialpuppeteeroverride (v0.28.0+).http_requests_total(v0.28.0+) recordsstatus="499"when the client closes the connection before the response is sent,408or503when the in-flight body budget drops or sheds a body, androute="(unmatched)"for unmatched routes, andopenwa_ingress_dedup_body_mismatches_totalcounts ingress deliveries that reuse adeliveryIdwith a different payload hash.
Upgrade to v0.27.1
- Adds
GET /api/sessions/{sessionId}/contacts/{number}/lid({ lid: string | null }), the reverse ofGET .../contacts/{lid}/phone; onwhatsapp-web.js,GET .../contacts/{lid}/phonealso answers{ phone: "<digits>" }directly when passed a phone number or@c.usJID. POST /api/infra/restartanswers409withcode: "RESTART_DATABASE_NOT_STARTED"whenDATABASE_TYPE=postgresandPOSTGRES_BUILTIN=true(pointing at the bundled host) and theopenwa-postgrescontainer is not running, orcode: "RESTART_ALREADY_RUNNING"when a restart is already in progress.POST /api/sessions/{sessionId}/messages/forwardstores the original message'stype, text (body), and media metadata (mediaUrl,mimeType,filename) on the new row instead of hardcodedtype: "text"andbody: "[forwarded]".
Upgrade to v0.27.0
- Back up both databases and both engine-auth directories (
sessions/andbaileys/) before starting the new version. AddChatStateDeletedAtaddschat_states.deletedAton the data database. WhenSEARCH_CONTAINS_ENABLED=true(defaultfalse), the gateway builds the message substring trigram index in the background after the HTTP port opens, andGET /api/search?match=containsanswers501until the index is ready. On PostgreSQL the build requiresCREATEon the schema and thepg_trgmandunaccentextensions (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) inmessages.frominstead of the bare phone number, matching messages sent from a linked phone and incoming messages;fromfilters onGET /api/sessions/{sessionId}/messagesandGET /api/searchmatch both forms. - The
message.ackwebhook and WebSocket event and themessage:ackplugin hook now fire only for messages the session sent itself (fromMe: true). Delivery receipts for incoming messages no longer emitmessage.ack. - When a message edit arrives and updates a stored message's text, the
message:persistedplugin hook fires again withmetadata.edited: true. DELETE /api/plugins/{id}clears the plugin's operator settings inplugins/registry.jsonfirst, then unloads the worker and deletes the plugin directory on disk (if that initialregistry.jsonwrite fails,DELETEanswers500and the plugin stays running). If removing the files fails after the registry entry is emptied,DELETEanswers400, the audit log recordspartial: truewithfileDeleteError, and the plugin stays disabled and does not reload on the next boot.- On the built-in engine plugins (
whatsapp-web.jsandbaileys),PUT /api/plugins/{id}/configremoves a stored top-level key when its value isnullso 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: trueis now deleted by the daily media retention job afterCHAT_MEDIA_ARCHIVE_TTL_DAYSalongside inbound archived media. - The PostgreSQL pool sends
statement_timeout,TimeZone='UTC', andsearch_pathas SQL statements on each new connection instead of startup packet options, so PgBouncer in session pooling mode works withoutignore_startup_parameters. Transaction pooling remains unsupported because boot migrations and background trigram index builds use session-level advisory locks. backup.shrecords a non-publicPOSTGRES_SCHEMAindatabase.schema, dumps only that schema withpg_dump -n(requiringpg_dump14+ whenPOSTGRES_SCHEMAis notpublic), prepends a prelude that renames any existing target schema to<schema>_pre_restore_<timestamp>withoutCASCADE, and movesCREATE INDEX idx_messages_body_trgmafter schemaGRANTs;restore.shprints thepsqlcommand with--single-transaction -v ON_ERROR_STOP=1and requires apsqlversion that enforces\restrict(13.22+,14.19+,15.14+,16.10+,17.6+, or18+) whendatabase.sqlopens with\restrict.
Upgrade to v0.26.0
- Back up both databases and both engine-auth directories (
sessions/andbaileys/) 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 unlesssessions/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 upSESSION_DATA_PATH(defaultdata/sessions/) before the first start and restore it before downgrading. An explicitPUPPETEER_EXECUTABLE_PATHkeeps selecting that browser. - Breaking (config): a production boot refuses a
METRICS_TOKENthat is the.env.exampleplaceholder or a known weak value such astestorchange-me, since the scrape endpoint is public. Set a long random token, or unset it to keep/api/metricsdisabled (it answers404). - A boot with
REDIS_TLS=trueor aREDIS_USERNAMEother thandefaultbeside the built-in Redis (REDIS_BUILTIN=truewith the bundled host, while Redis, the queue or the cache is on), or withDATABASE_SSL=truebeside the built-in PostgreSQL (DATABASE_TYPE=postgresandPOSTGRES_BUILTIN=truewith 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 withSTORAGE_TYPE=s3and anS3_ENDPOINTwithouthttp://orhttps://(for exampleminio:9000) still starts, on the local media directory, and logs an error; add the scheme. - A
POSTGRES_BUILTIN,REDIS_BUILTINorMINIO_BUILTINflag 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_FILESis 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 to0to query for every send as before.QUEUE_PREFIXsets 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 keepsbull, 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 /infothrough it is refused, and a client of your own that reads it needsINFO: 1on 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 answers503withRetry-After, and other ingress deliveries are held and dispatched once it is up (with the queue off, by the reconciler afterINGRESS_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 answer409just after a restart. - An explicit
nullfor 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 sendsnullfor "not provided" must leave the key out. - A per-session plugin config or an integration instance that sets a
net.allowConfigHostskey (for examplebaseUrl) to another origin than the layer beneath no longer inherits that layer'ssecretfields, 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 configPATCHof an instance whose plugin is not loaded answers409. - 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
400where they were accepted or answered500: 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 bulkoptions, a bulk item'scontentand media,customLinkPreview, the infrastructure config sections or a status media source) and an object in a list field (for example a webhook'sevents), a body nested more than 100 levels, amuteUntilabove 9007199254740991, achatId,fromChatIdortoChatIdthat is notlocalpart@hostor is a JSON number, and an object sent forallowedChats,allowedSessionsorallowedIpson an API key, which was stored as an empty list, meaning no restriction.POST .../groups/{groupId}/membership-requests/approveand/rejectanswer400for 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-picturesleaves 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-codeanswers409for 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
DELETEto finish, orPOST /api/sessions/{sessionId}/startto 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}andDELETE /api/integration/plugins/{pluginId}/instances/{instanceId}wait up to 10 s for another open database transaction and answer503when 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
deletingordeleting-stoppedwithout 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_eventssession index and, on SQLite, checks the message search index against all stored text and rebuilds it when they differ. RaisestartupProbe.failureThresholdor 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
409on 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.shstops before it copies anything when a path from the archive's own.env.generatedleaves 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./.envto 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
conversationIdJSON 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}/redrivereplays and counts only the dead letters written under the instance's current session binding. - A plugin catalog with an entry whose
id,name,versionor text field is not text is refused with400; a privatePLUGIN_CATALOG_URLcatalog 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(sessionDataPathfor whatsapp-web.js,baileys.authDirfor Baileys) is no longer used; before upgrading, move those session folders toSESSION_DATA_PATHorBAILEYS_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/configorPUT /api/plugins/baileys/configbefore v0.24.0 stored every environment-derived engine setting of that time, such as thepuppeteersettings, which still override.env; with OpenWA stopped, remove the keys you did not set on purpose, or the wholeconfig, from that plugin's entry inplugins/registry.jsonunderPLUGIN_STATE_DIR(default./data). - The first boot of v0.24.0 builds two indexes,
(sessionId, chatId, createdAt)onmessagesand(sessionId, createdAt, id)onbaileys_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=0to 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
KILLfor 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=truecan restart those sessions after upgrade. - New Baileys pairings default to the linked-device name
Ubuntu. SetBAILEYS_BROWSER_NAME=OpenWAbefore restart only if you need the old name; linked sessions are unchanged. PORTrejects surrounding or whitespace-only padding, andWEBHOOK_SHUTDOWN_DRAIN_MSrejects non-integers such as30s. Infrastructure saves reject invalid ports/pool sizes and unwritable local storage paths.- PostgreSQL TLS now matches
DATABASE_HOSTeven when it is an IP address. Use the certificate's DNS name or add the IP to its SANs; a certificate forlocalhostdoes 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 underNODE_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 forINGRESS_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>underSESSION_DATA_PATH(defaultdata/sessions) for whatsapp-web.js and<id>underBAILEYS_AUTH_DIR(defaultdata/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/jsonandapplication/x-www-form-urlencodedbodies. A delivery that carries a body of any other type, JSON sent astext/plainor anapplication/*+jsontype included, now gets415where 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.
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.
- 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 withALTER 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. TheDEFAULT now()columns took the server's zone, so a gateway in UTC alone does not settle it. TZreaches the container. The bundled Compose files forwardTZ, defaulting toUTC; up to v0.23.5 aTZin.envnever reached the container. One left in.envtherefore takes effect on upgrade: it moves theprettylog timestamps, the lines NestJS's console logger prints itself (through v0.23.7; from v0.24.0 those are OpenWA log lines and follow theprettystamps like the rest), and the local day thetodaymessage counts cover. Stored timestamps stay UTC. The forwarded value also shadows aTZline indata/.env.generated, so a Compose gateway that took its zone from that file runs in UTC after the upgrade unless.envor the shell runningdocker composesetsTZ; move the value to.envto keep it.- A mixed-case or padded
POSTGRES_SCHEMAis refused, naming the rule: at boot, by the data-DB:prodmigration scripts above before they connect, and with400when 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 withpg_. - Rate limits. A
429from a rate-limit window (theshort,mediumandlongwindows, and the ingressinstanceandingress-ipbuckets) carries a plainRetry-Afterin seconds next to the suffixedRetry-After-<window>, so a client that honors it now waits (up to an hour at the defaults when thelongwindow shed the request) instead of retrying at once. The send-pacing refusal still reports its wait only asretryAfterSecondsin the body, and the MCP and Bull Board IP limits answer429with noRetry-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 reachesMCP_IP_RATE_LIMIT_MAXsooner. Per-client limits key an IPv6 client on its /64: where several clients reach the gateway from one IPv6 network, raise theRATE_LIMIT_*,INGRESS_IP_LIMIT,WS_RATE_LIMIT_HANDSHAKE_MAXandMCP_IP_RATE_LIMIT_MAXlimits, andINFLIGHT_BODY_BUDGET_BYTESfor 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/voiceor.../convert/video, and the Baileys link preview of a text send) is fetched through the session's proxy. SetSESSION_PROXY_URL_FETCH=falsewhen a session proxy is a WhatsApp-only route that cannot reach arbitrary media hosts. Through anhttporhttpssession 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; asocks4orsocks5proxy, orSESSION_PROXY_URL_FETCH=false, keeps it. When an admin opens the dashboard, the gateway asksapi.github.comfor the latest release, caching the answer for six hours (fifteen minutes after a failure). That request goes out directly, not throughHTTP_PROXYorHTTPS_PROXY; setUPDATE_CHECK_ENABLED=falsewhere that egress is not wanted. - WebSocket clients. Command replies arrive on the
messageevent as well as through the ack callback, so a client that passes an ack and also listens onmessagesees 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 anUNAUTHORIZEDframe 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. OnAPI key authorization changed; please reconnect, reconnect and resubscribe, unless the change now refuses the key at the handshake (anallowedIpslist that excludes the client, or an expiry that has already passed; a key that gainedallowedChatswas refused there through v0.24.0 and connects from v0.25.0). AfterAPI key has been deletedorAPI key has been revoked, and usually afterAPI 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
responseanswers202 acceptedwhere it answered200 duplicate. The gateway keeps no record of a repeat either: theingress_eventsdedup row is written by the first delivery of each id, a repeat adds no row or field, and the gateway logs nothing for it unlessDATABASE_LOGGINGis on. Under PostgreSQL's default logging settings, the database server's own log still shows each repeat, key included, as a unique-constraint error onUQ_ingress_events_instance_delivery. An installed plugin whose ingress manifest declares a route that is not one URL path segment, a non-numerictoleranceSec, a1xxack 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
urlthat is not an absolutehttp(s)URL answers400on a send, status, profile-picture or group-picture route (in a bulk request, an item whoseurlis not one refuses the whole request with400and nothing is queued, unless theurlcontains a{: that one is checked oncevariablesare applied and fails its item like any other send failure, which stops the batch there understopOnError), and media conversion refuses an input that is not a single-file media container with400. - 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 throughGET /api/sessions/{sessionId}/contacts/{contactId}withisMyContact: false. Also on Baileys, a list prompt (listMessage) and a tapped button, template or list reply (buttonsResponseMessage,templateButtonReplyMessage,listResponseMessage) arrive astype: "text"with their display text inbody, where they arrived astype: "unknown", so a consumer that filters ontypenow sees them as text. Baileys sessions also deliver what WhatsApp queued while they were down, the upgrade window included: messages received meanwhile dispatchmessage.receivedand those sent from the phonemessage.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}/rejectanswers501, and aWWEBJS_ONBOARDING_CONTINUE_LABELSlabel is clicked only on a button inside a[role="dialog"]or[aria-modal="true"]container. - Plugins. The
session:createdhook carries the session in the REST shape, withoutproxyUrlorconfig. A takeover or resolved conversation recorded on a chat's@lidform 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@lidmapped 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_LEVELisdebugortrace. Logs an earlier release wrote at those levels may hold it; rotate that proxy password.
- With
WEBHOOK_SSRF_PROTECT=false, deliveries no longer follow redirects: a receiver that answers3xxnow fails the delivery. SetWEBHOOK_SSRF_REDIRECTS=trueif the redirect is legitimate.SSRF_ALLOWED_HOSTSentries 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 a400. - Plugin installs from a URL require a
#sha256=<64 hex>pin underNODE_ENV=production(the compose default),https:URLs included. Action required: catalog installs without a pin fragment now fail. Pin the URL, or setPLUGIN_INSTALL_REQUIRE_PIN=false. Plain-http:installs already needed the pin since v0.19.0.
- Production boot refuses a set
API_MASTER_KEYshorter 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-catalogandPUT /api/settingsare removed — both always answered501, so nothing that worked before stops working. Calls to the old URLs now get404.GET /api/settingsandsend-productare unchanged.- The session routes' path parameter is uniformly
{sessionId}inopenapi.jsonand 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:
- 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.updatedAtandbaileys_stored_messages.createdAt. The last three carry aDEFAULT 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 oldTZ, or the host's zone for a host install that set none), which resolves daylight saving per row. Leavinglid_mappings.updatedAtandchat_states.updatedAtas they are also mis-ranks the boot preload of both caches, which orders by that column under a cap. - Clear the lease, do not convert it.
sessions.claimedAtandsessions.leaseExpiresAtare 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 innodeIdtreats the session as held elsewhere, andPOST /api/sessions/{sessionId}/startanswers409there until the lease lapses (a container recreated on upgrade takes a new hostname, the defaultNODE_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
UPDATEmoves 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.createdAttakes the treatment of the otherDEFAULT 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 thedatabase.sqlin abackup.sharchive, 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:
- Confirm
imported === true. If it isfalse, the data was not written — readwarnings, fix the cause, and re-run the import. - Only then compare the import
countsagainst the exportcountsto 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.
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": truein the payload. The import stops each orphaned engine before the replace runs, andrestartRequiredstaysfalse. The response reports the outcome per engine instoppedOrphanEnginesandfailedOrphanEngines. Since v0.26.0 each session it stops is recorded as asession_stoppedaudit 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 carriesrestartRequired: truewith their ids inorphanedEngines— 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:
filePathmust point inside thedata/directory. The import rejects any path outside it with400 Bad Request— a path-traversal guard. Keep the archive wherestorage/exportwrote 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 thanSTORAGE_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 Requestwith 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/importcopies into the active backend without deleting the source files. On S3 the store still readsSTORAGE_LOCAL_PATH(default/app/data/mediain the container) as a fallback: what is left there is listed, counted, served when the bucket has no copy, and archived byscripts/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.
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.
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 queueThe 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"'
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.
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.
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.
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.
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.
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.
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
| Problem | Likely cause | Fix |
|---|---|---|
403 Forbidden on an /api/infra/* call | API key lacks the ADMIN role, or is restricted to specific sessions or (v0.23.6+) to selected chats | Use an admin key with no session or chat restriction. See Authentication. |
import-data wiped data you wanted to keep | Import replaces, it does not merge | Restore 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 it | ALTER DATABASE "<database>" SET TimeZone='UTC', or let the statement through the pooler. |
| Timestamps read hours off after upgrading to v0.23.6 | PostgreSQL data written by a gateway, or a database server, that ran outside UTC, and not converted before the first start | Follow 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 Conflict | The 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 413 | The 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 Request | filePath 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 corrupt | Use the path storage/export returned, import soon after the restart, and re-export a removed or damaged archive. |
| Session won't reconnect after a move | Auth data truncated or corrupted in transit | Re-scan the QR code for that session. |
Permission denied on the data directory | The 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 itself | See Fix file ownership on bind mounts. |
| Migration command errors on the prod image | Ran 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 boot | The 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 rebuild | Run 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 restored | Set 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 504 | whatsapp-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 boot | Raise 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 rollback | The 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 user | Make 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 column | Fix 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.