Reclaim Synapse Media Disk Space Without Breaking Shared Files
Find what is filling Synapse storage, set safe media retention, and purge remote cache without deleting files directly from disk.
If Synapse’s media repository is filling the disk, first confirm which directory or volume is growing, then use Synapse’s supported retention settings or Admin API to remove media. Do not delete files directly from media_store: Synapse keeps media metadata in its database, and removing files behind Synapse can leave broken references or make cleanup hard to audit. The safest policy depends on whether the space is used by local uploads, cached media from other homeservers, thumbnails, or another service sharing the same disk.
Synapse’s media repository stores locally uploaded avatars, attachments, and thumbnails. It also caches media fetched from remote Matrix servers and resources used for URL previews. These are distinct from the Synapse database, container logs, and any external media repository. A full root filesystem does not by itself prove that media_store is the cause.
On the host or inside the container that owns the mounted data, compare filesystem usage with the Synapse data directory. Replace the example path with the value in your deployment:
df -h
du -h --max-depth=1 /path/to/synapse-data
du -sh /path/to/synapse-data/media_store
Synapse’s media_store_path defaults to media_store, commonly under the data directory, but installations can override it. Containers can write to a mounted volume whose actual storage is on the host. Check homeserver.yaml, your container volume mappings, or your orchestrator’s persistent-volume configuration before concluding that a host path is safe to change. If the media directory is not the largest consumer, investigate the component that du shows instead.
Verified behavior: Synapse’s media_retention setting can expire local media and cached remote media after periods without access. Access includes loading media in a room or downloading it. If an item has never been accessed, Synapse uses its creation time. Both the original media and its thumbnails are removed. Cleanup runs on the media repository worker, which may be the main Synapse process.
What depends on your use case: Remote cached files can generally be fetched again from their originating homeserver when requested after removal. Locally uploaded files are hosted by your server, so purging them can make old attachments or avatars unavailable. Choose local retention only if your users accept that consequence; a longer local lifetime or no automatic local cleanup may be more appropriate for a community that treats old attachments as an archive.
What retention does not mean: quarantining media blocks access but does not delete the file or its thumbnails. It will not free the disk space you need. If you need to preserve a quarantined item while removing other data, keep the distinction clear: quarantine is a moderation control, while retention and deletion are storage controls.
Back up the active configuration before editing it. Add a top-level media_retention section or update the existing one. For example, this policy expires local media after 180 days without access and remote cache entries after 30 days:
media_retention:
local_media_lifetime: 180d
remote_media_lifetime: 30d
These values are examples, not universal recommendations. Set the local period according to your retention obligations and expectations for old room content. If you only want to control the cache for remote media, configure just remote_media_lifetime; an unset or null lifetime means that type will not be purged automatically. Synapse also documents that quarantined media and local media protected from quarantine are excluded from retention cleanup.
Apply the configuration using the deployment’s normal restart or reload process, and verify that the media repository worker is running with enable_media_repo: true. If Synapse uses a separate media worker, configure the policy where the media repository service is enabled. A valid YAML edit does not immediately reclaim all space: the worker must run cleanup, and only media older than the chosen access cutoff qualifies.
If the disk is already critical, Synapse provides administrative endpoints for cleanup. These actions permanently remove media. Before using them, back up the database and media data, confirm that the URL targets your own homeserver, and use a server administrator access token over HTTPS. Keep the token out of shell history and shared logs.
To purge old cached remote media, call the documented endpoint with a cutoff timestamp in milliseconds since the Unix epoch:
POST /_synapse/admin/v1/purge_media_cache?before_ts=<unix_timestamp_in_ms>
For example, a shell can calculate a cutoff 30 days ago with GNU date:
cutoff=$(date -u -d '30 days ago' +%s000)
curl -X POST "https://matrix.example.com/_synapse/admin/v1/purge_media_cache?before_ts=$cutoff" \
-H "Authorization: Bearer YOUR_SERVER_ADMIN_ACCESS_TOKEN"
The response reports how many cached items were deleted. If users request those remote files again, Synapse will fetch them again from the originating server; this can restore disk usage for popular media.
The local media deletion API can delete local media based on last access time and, optionally, a minimum size. Its current endpoint is POST /_synapse/admin/v1/media/delete?before_ts=…; the older endpoint containing <server_name> is deprecated since Synapse 1.78.0. The cutoff is last access, not upload date, and the keep_profiles option defaults to true. Because this deletion can remove files users expect to remain available, prefer configured retention unless you have identified an appropriate cutoff and accept the effect. Follow the official API reference for parameters and your installed Synapse version.
After the cleanup worker has had time to run, check df -h and the media directory size again. For an API purge, confirm the response’s deleted count and compare the relevant directory before and after. Check Synapse logs for configuration or worker errors. If the directory remains large, inspect whether your deployment writes media to a configured provider or separate volume; the Synapse local media deletion API does not affect media stored in an external media repository. Do not assume a successful API response will reduce the host filesystem if the files live elsewhere.
Find what is filling Synapse storage, set safe media retention, and purge remote cache without deleting files directly from disk.
Review device activity, deactivate confirmed inactive Synapse accounts through the Admin API, and learn what the optional erase flag actually removes.
Find whether PostgreSQL memory comes from query work, shared buffers, connections, or maintenance, then make targeted Synapse-safe changes.
Trace slow Matrix room joins to one remote homeserver, federation backoff, local database load, or an outbound sender queue before changing Synapse settings.
Stop open account creation on a self-hosted Synapse server, or keep sign-ups invite-only with limited-use registration tokens.
Clear Element's unverified-session warning using a trusted device or recovery key, with checks that protect your encrypted chat history.
Distinguish database lock contention from expired WebDAV locks, then choose and configure the right ownCloud 10 fix.
Trace a blank ownCloud Web screen to browser cache, missing web assets, service errors, or reverse-proxy URL settings with targeted checks.
Set ownCloud’s web PHP memory limit, restart the matching service, and verify the active value without confusing it with CLI settings or upload limits.
Find out whether MySQL, PHP, socket settings, or database permissions are blocking ownCloud 10, then verify a safe fix.