Upgrading your gateway
Upgrade your gateway to each new release to get its fixes and security updates. Your indexed data is stored in the data/ directory on the host, not inside the containers, so upgrading keeps your data and indexing progress.
Before you start
- Your gateway must have been set up from a git clone of the
ar-io-noderepository. If it wasn't, follow the installation instructions. - Find your current release in the
releasefield ofhttps://<your-gateway>/ar-io/info. A release ending in-premeans you run thedevelopbranch; the steps below move you tomain. - Read the release-specific steps for every release you are upgrading past, and the GitHub releases or CHANGELOG for new environment variables. New releases are also announced in the ar.io Discord.
Upgrade your gateway
Run these commands from your gateway's directory. On Windows, leave out sudo.
Pull the new release
git checkout main
git pullUpdate .env
- Add or change any variables the release notes ask for.
- If you pin image tags in
.env(CORE_IMAGE_TAG,ENVOY_IMAGE_TAG,OBSERVER_IMAGE_TAGand others), update them to the new release's values, or remove them to use the defaults indocker-compose.yaml. A pinned tag overrides the default, so a stale pin keeps the old image running.
Stop the gateway
sudo docker compose downStart the gateway
sudo docker compose up -dDocker pulls the images named in docker-compose.yaml, so you don't need --build.
If you normally start your gateway with -f files or --profile flags (for example -f docker-compose.yaml -f docker-compose.grafana.yaml, or --profile clickhouse), pass the same ones to down and up. Passing any -f stops Docker Compose from loading docker-compose.override.yaml automatically, so name it too if you use one.
Check the upgrade
Check that https://<your-gateway>/ar-io/info shows the new release, that every container is running (sudo docker compose ps), and that the core logs show no repeating errors (sudo docker compose logs -f core).
Free disk space (optional)
Old images stay on disk after an upgrade. To remove every image no container uses:
sudo docker image prune -aOther Docker projects
This also removes unused images of any other Docker project on the machine.
Release-specific steps
Some releases need a step beyond the upgrade above. Do these when you upgrade to the release named, or past it. Each release's CHANGELOG entry has the full list of changes.
Release 88
- Purge cached JSON wrappers. Before Release 88, a gateway could cache arweave.net's JSON description of a data item in place of the item, and then serve it with the wrong content type and hash. Observers report these as
dataHashDigestandcontentTypemismatches. Release 88 fixes the fetch, but copies already cached keep being served until you purge them. A wrapped copy starts with{"accept-ranges". For each affected ID, call the newPOST /ar-io/admin/invalidate-data, then purge any NGINX or CDN cache in front of the gateway. See Purging cached JSON wrappers. - Expect 503s for slow chunks.
/chunk/<offset>now answers503withRetry-After: 5, not404, when it couldn't fetch a chunk in time. Your dashboards will count these as 5xx errors. - Raise
GATEWAYS_GQL_MAX_HOPSon a federation-only gateway. GraphQL queries fanned out toGATEWAYS_GQL_URLSnow stop afterGATEWAYS_GQL_MAX_HOPSgateways (default 2). If your gateway setsGATEWAYS_GQL_INCLUDE_LOCAL=falseand other gateways query it through one more hop, raise it, for example to 3.
Release 87
- Upgrade gateways that take
parquet-l1bands. Gateways that subscribe toparquet-l1need Release 87 to take bands published in the newl1-4layout. Withl1-4bands,L1_BAND_IMPORT_ALLOW_UNVERIFIEDis no longer needed. - Remove
INDEX_EXPORT_L1_WITNESS_MAX_MISSINGfrom.envif you set it. The setting is gone.
Release 86
- Upgrade now: this is an urgent security release. It moves the core image from Node.js 20 to 22.23.4, and the default observer image to Node.js 22.23.4, to fix a remote code execution bug in Node's Brotli decoder (CVE-2026-111497) and two TLS hostname-check bypasses. Upgrade both images.
- Update a pinned
OBSERVER_IMAGE_TAGorCORE_IMAGE_TAG. A tag you set in.envoverrides the new default and keeps the vulnerable image. Update it, or remove it. - Use Node.js 22 if you run from source. The repository's
.nvmrcnow names Node.js 22. - Drop a Brotli workaround. If you stopped Brotli decoding with a
NODE_OPTIONS=--requireshim, you can remove it once you run the new image. - L1 band imports are stricter. With
L1_BAND_IMPORT_ENABLED=true, the gateway refusesl1-3bands below height 2,000,000 unless you setL1_BAND_IMPORT_ALLOW_UNVERIFIED=true. Release 87'sl1-4bands don't need it. - Publishers of
parquet-l2indexes: upgrade subscribers first. Every band is now built in thel2-2layout, and a subscriber older than Release 86 refusesl2-2bands.
Release 85
- Index Sharing is on by default. A plain
docker compose up -dnow also starts the Index Sharing sidecar and its torrent engine. Your gateway subscribes to turbo-gateway.com's root transaction index, downloads about 22 GB of bands, searches them first for root transaction and offset lookups, and seeds them to other gateways. Before upgrading:- Keep at least 64 GiB free on the filesystem that holds
data/indexes(INDEX_SWARM_MAX_DISK_BYTES, 64 GiB by default with the default subscription), or set a lower budget. - Allow about 0.4 GB more memory: about 90 MB for the sidecar and 300 MB for the engine.
- Make sure nothing else on the host uses port 6881 (the engine's peer port, TCP and UDP) or port 6969 on
127.0.0.1(the tracker, which the sidecar publishes on the loopback address only). Neither container starts without its port. Opening 6881 to the internet is recommended, not required. - On metered bandwidth, lower
INDEX_SWARM_UPLOAD_LIMIT_BYTES_PER_SEC(10 MB/s by default) andINDEX_SWARM_UPLOAD_DAILY_LIMIT_BYTES(100 GB a day). - To opt out, set
INDEX_SWARM_SUBSCRIBE=[]in.envbefore you upgrade. Bands already installed stay in use. On Release 85 they are still seeded; from Release 86 opting out also stops seeding them, and the files are kept. See Turning it off. - If you set up Index Sharing on Release 84, your settings still apply: an
INDEX_SWARM_SUBSCRIBE,INDEX_SWARM_ENGINE_AUTH,INDEX_SWARM_MAX_DISK_BYTES,CDB64_ROOT_TX_INDEX_SOURCESorROOT_TX_LOOKUP_ORDERyou set is used unchanged, and installed bands are kept, not downloaded again. A subscription you set has no disk cap unlessINDEX_SWARM_MAX_DISK_BYTESis set; the Release 84 setup script set one. - If your sidecar ran over HTTP only on Release 84, it now gets the torrent engine too, with a generated password. To keep HTTP only, see HTTP only.
- Keep at least 64 GiB free on the filesystem that holds
- Range misses now fill the cache in the background.
BACKGROUND_CACHE_RANGE_MAX_SIZEnow defaults to 10 GiB (it was0, off) andBACKGROUND_CACHE_RANGE_CONCURRENCYto 4 (it was 1). A range request for an uncached item fetches only the range, and then the whole item, up to 10 GiB, is fetched into the cache in the background. Expect the data cache to grow faster with items read by range, such as video, SQLite or Parquet files. To keep the old behaviour, setBACKGROUND_CACHE_RANGE_MAX_SIZE=0. - JSON is served without an added charset. A JSON item is now sent with the
Content-Typeit was uploaded with, notapplication/json; charset=utf-8. Responses an NGINX or CDN cache already holds keep the old header until they expire or are purged. - Drop
tip-5.arweave.xyzfrom your own chunk node lists. Release 85 removed it from the default preferred chunk nodes because it stopped answering. If you setPREFERRED_CHUNK_GET_NODE_URLSorPREFERRED_CHUNK_POST_NODE_URLS, remove it there too. - Upgrade the Envoy image with core. Peers now announce to an Index Sharing publisher's tracker through the gateway, at
/ar-io/indexes/announce, and Envoy routes that path. An older Envoy passes it to core, which answers404, so every announce fails without an error. If you setENVOY_IMAGE_TAGin.env, update it too. - Index Sharing services run the core image. The
index-swarmsidecar, the engine's setup step (index-swarm-engine-init) andindex-exportrun the core image (CORE_IMAGE_TAG, orINDEX_EXPORT_IMAGE_TAGforindex-exportwhen set), so they move to the new image with core when you pass your usual-ffiles and--profileflags. The sidecar and the engine start by default;index-exportis in a compose profile that is off unless you name it. - Torrent publishers: move peers to the gateway's tracker route. The setup script keeps an existing
INDEX_SWARM_TRACKERS, so a publisher set up on Release 84 still announces to the tracker's own port (6969), which must stay reachable. From Release 85 that port is published on127.0.0.1only. Until you move peers to the gateway's route, setINDEX_SWARM_TRACKER_HOST_IP=0.0.0.0in.envbefore you upgrade, or peers can't reach the tracker. To announce through the gateway instead, setINDEX_SWARM_TRACKERS=https://<your-gateway>/ar-io/indexes/announceand restart the sidecar. On its next scan it rebuilds each band's.torrentwith the new tracker. The infohashes don't change, since trackers sit outside the info dictionary. - Update a pinned
OBSERVER_IMAGE_TAG. Release 85's observer runs the offset checks on every gateway each epoch, including yours: a gateway fails when all 4 sampled offsets fail, so upgrade core with the observer. A tag you set in.envoverrides the compose default, so update it there. - Purge gzip bodies cached before the upgrade. Before Release 85, a gateway could serve a gzip-compressed upload decoded, either still labelled
Content-Encoding: gzipor without the header. Bodies an NGINXproxy_cachestored before the upgrade keep the wrong body until they expire or are purged. Cache bypass header shows how to refresh one. When your gateway finds a decoded copy in its own cache, it logs a warning and counts it inserved_content_encoding_dropped_total. - Don't trust gateways older than the gzip fix. A gateway older than Release 85 can serve a gzip-compressed upload decoded. Release 85 refuses those bodies when the response's headers give them away, but a decoded body sent with neither
Content-Encodingnor the tag headers can't be told apart. Don't list such gateways inTRUSTED_GATEWAYS_URLSorTRUSTED_GATEWAY_URL.
Getting help
If something doesn't work after an upgrade, see Troubleshooting or ask in the ar.io community Discord.
How is this guide?