Troubleshooting

Upgrade services

Data schemas are generally backwards-compatible across minor patch versions within the same major release. Before upgrading, always review the target release notes and create restorable database backups. Prefer upgrading to the latest official release tag marked with the green Latest badge on GitHub Releases; specify an exact tag if your environment requires pinned versions.

Docker Compose deployment

cd openim-docker
git fetch --tags
TARGET_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/openim-docker/releases/latest)")
git checkout "$TARGET_TAG"
echo "upgrade openim-docker to stable release tag: $TARGET_TAG"

Verify that the image tags in .env match the target release. Adjust any changed environment variables according to the release notes, then pull images and recreate containers:

docker compose down
docker compose pull
docker compose up -d

Source build deployment

cd open-im-server
mage stop
git fetch --tags
TARGET_TAG=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/openimsdk/open-im-server/releases/latest)")
git checkout "$TARGET_TAG"
mage
mage start

If ChatServer is deployed alongside OpenIMServer, upgrade ChatServer to its corresponding compatible release tag concurrently.

Migrate local component data

When dependencies are launched via Docker Compose, persistent data for MongoDB, Redis, Kafka, Etcd, and MinIO resides in the components/ directory of the deployment repository. Before moving data volumes, stop all application services and dependent containers, and take a verified backup.

For Docker Compose deployments:

docker compose down

For source deployments:

mage stop
docker compose down

Move the entire components/ folder to the target storage mount, update DATA_DIR in .env to point to the new location, and restart the stack:

docker compose up -d
mage start  # Required only for source builds

After startup, do not rely solely on container health checks. Run through the end-to-end verification checklist in Deployment verification to validate REST APIs, WebSocket handshakes, message routing, and file uploads.

Clear test data

Warning: This procedure permanently purges all local component databases. Use this only in development or staging environments where data can be safely discarded. Always ensure you have restorable backups before proceeding.

Stop all active services and containers:

mage stop           # Required for source builds
docker compose down

Delete the components/ directory in the deployment repository root. After restarting the backend, uninstall and reinstall client applications to clear local client-side SQLite databases. Never run this cleanup process in production environments.

Text messages work but image uploads fail

This failure mode usually indicates that the external endpoint for object storage is unreachable from client networks.

For source deployments, update config/minio.yml:

externalAddress: http://your-server-ip:10005

For Docker Compose deployments, update .env:

MINIO_EXTERNAL_ADDRESS="http://your-server-ip:10005"

When deploying with public domain names, set this value to the HTTPS /im-minio-api proxy path documented in Domain configuration, and confirm that client devices can establish HTTPS connections to that endpoint.

Reduce MongoDB and Kafka memory usage

In memory-constrained development or testing environments, reduce memory pressure by setting cache limits and Java heap sizes in docker-compose.yml. These limits reduce database and message queue throughput and should not be applied to production workloads.

The MongoDB service is named mongo in openim-docker and mongodb in open-im-server:

mongo:
  environment:
    - wiredTigerCacheSizeGB=0.5

For Kafka, configure JVM heap limits:

kafka:
  environment:
    KAFKA_HEAP_OPTS: '-Xms256m -Xmx256m'