How to properly delete media files

[sergiy-shchur]

I sent a message with an attachment. Then I deleted that message. Then I noticed that the file wasn't removed on the server (which is probably a bug?). Then I tried to delete that file:
!admin media delete-by-event --event-id $CwrxPTDoN***
Command failed with error:
Parsed event ID but found no MXC URLs.
Since I deleted the message, I can't get the MXC URL. Thus !admin media delete mxc url is not an option here.
What am I doing wrong? Any help appreciated.

[MLuc24]

You're not doing anything wrong, and the part you flagged as "probably a bug" isn't one — in Matrix, redacting a message strips the event's content, but the upload lives in the media store as an independent object with no reference counting back to events. Every homeserver behaves this way, so deleting the message was always going to leave the file behind. Unfortunately it also destroys the only pointer you had, which is exactly why delete-by-event now reports:

Parsed event ID but found no MXC URLs.

The command is working correctly; the redacted event genuinely no longer contains a URL to parse.

Since the MXC is gone, you need a command that selects by something other than the URL. Looking at the media admin commands, the practical one is delete-range, which works off filesystem last-modified time:

DeleteRange {
    /// - The relative time (e.g. 30s, 5m, 7d) within which to search
    duration: String,
    /// - Only delete media created after [duration] ago
    #[arg(long, short)]
    newer_than: bool,
    /// - Long argument to additionally delete local media
    #[arg(long)]
    yes_i_want_to_delete_local_media: bool,
}

Two things to be careful about. It defaults to remote media only, so for your own upload you need the local flag, and it deletes everything in the window — not just your file. So make the window as tight as you can around when you sent the message:

!admin media delete-range 30m --newer-than --yes-i-want-to-delete-local-media

The other option, if this is a personal server and you don't mind the collateral, is delete-all-from-user <username>, which takes a plain username and clears that user's local media.

Going forward the lesson is ordering: run delete-by-event before redacting, while the event still carries the MXC URLs. That path works exactly as intended and avoids the guesswork entirely.

[sergiy-shchur]

Thank you very much for your detailed answer. I just tried another quick test. I sent a file. I DIDN'T delete the message. I tried to delete media using the same command !admin media delete-by-event --event-id $CwrxPTDoN***. But I got the same result Parsed event ID but found no MXC URLs.. Is there any other way to perform cleanup of such orphan files?
I see an option #media_startup_check = true. As far as I understand it will cleanup database entries for missing files. In other words, if I remove a file from a filesystem, it will remove all references to this file in the database.

[MLuc24]

That test is decisive, and it rules out my explanation — thanks for running it. If an intact event fails the same way, redaction was never the cause.

Looking at delete_by_event.rs, it reads the stored PDU and tries three places:

let mut mxc_urls = Vec::with_capacity(3);
mxc_urls.extend(url_mxc_from_content(content));       // content.url
mxc_urls.extend(thumbnail_mxc_from_content(content)); // content.info.thumbnail_url
mxc_urls.extend(file_mxc_from_content(content));      // content.file.url

All three read content straight from get_pdu_json. Which means the question is what your server has stored in that field — and if the room is encrypted, it's ciphertext. An m.room.encrypted PDU's content is algorithm, ciphertext, sender_key, session_id and so on. There is no url, no info.thumbnail_url, no file.url, because the MXC lives inside the encrypted payload that the server can't read. All three extractors return nothing, and you get exactly the message you're seeing.

That fits both your tests identically, which the redaction theory didn't. Is the room in question encrypted? If so, delete-by-event can't work there by construction, and it isn't a bug in the command — it's a limit of what a homeserver can see.

The way around it is to get the MXC from something that can decrypt, namely your client. In Element, open the message menu and use View Source; for an encrypted event it shows the decrypted content, and the url (or file.url) inside it is the mxc://… you need. Then the direct command works:

!admin media delete --mxc mxc://your.server/AbCdEf...

If you accumulate several, !admin media delete-list takes a codeblock of MXC URLs in one go.

On media_startup_check — your reading is right, and the docs are explicit:

Scan the media directory at startup. Removes database entries for files that no longer exist on disk (when prune_missing_media is enabled), and upgrades Conduit-era symlinks (when media_compat_file_link is enabled).

So deleting the file from the media directory and restarting will clear the dangling row, provided prune_missing_media is on too — it's gated on that, not on media_startup_check alone. It's a reasonable cleanup route for orphans you can't address any other way, though it means a restart per cleanup, so I'd still prefer pulling the MXC out of the client for one-off files.

[sergiy-shchur]

Yes. The room is encrypted. And yes, I can see "url": "mxc://..." in the decrypted content. But when I delete the message, the decrypted content is gone. That's why I was trying to delete media by the event-id. It would be nice to see it documented that only unencrypted rooms' event-ids can be used with this command.
And one last observation, I just tried this command !admin media delete --mxc mxc://... and I got strange result
Command failed with error: Deleted the MXC from our database and on our filesystem. The file indeed was removed but the beginning of the phrase is confusing.

[MLuc24]

That confusing message is an actual bug, not you misreading it. The whole body of src/admin/media/delete.rs ends with Err!("Deleted the MXC from our database and on our filesystem."), so the success text is being returned down the error path, and the admin bot dutifully prefixes it with "Command failed with error:". The file really was deleted, which is why you saw both halves contradict each other. Worth opening as its own issue since it's a one-line fix and completely separate from your original question — anyone deleting media hits it. Your documentation point is fair too, and I'd say it lands harder now that you've confirmed the room is encrypted: delete-by-event can only ever work on unencrypted rooms, and nothing in the command's help says so, so the failure looks like a bug in the command rather than a limit of what the server is able to see. Given how much of Matrix is encrypted by default these days that's probably the more common case, not the edge case. And you're right that deleting the message first closes the only door — once the decrypted content is gone from your client there's no way back to the MXC, so for encrypted rooms the order really has to be grab the URL from View Source, delete the media, then delete the message.