diff --git a/roles/custom/matrix-media-repo/tasks/main.yml b/roles/custom/matrix-media-repo/tasks/main.yml
index 03c26ec5b..4bf63251d 100644
--- a/roles/custom/matrix-media-repo/tasks/main.yml
+++ b/roles/custom/matrix-media-repo/tasks/main.yml
@@ -6,6 +6,9 @@
     - install-all
     - install-matrix-media-repo
   block:
+    - when: matrix_media_repo_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
+
     - when: matrix_media_repo_enabled | bool
       ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
 
diff --git a/roles/custom/matrix-media-repo/tasks/validate_config.yml b/roles/custom/matrix-media-repo/tasks/validate_config.yml
new file mode 100644
index 000000000..fd9282d67
--- /dev/null
+++ b/roles/custom/matrix-media-repo/tasks/validate_config.yml
@@ -0,0 +1,22 @@
+---
+
+- name: (Deprecation) Catch and report renamed settings
+  ansible.builtin.fail:
+    msg: >-
+      Your configuration contains a variable, which now has a different name.
+      Please change your configuration to rename the variable (`{{ item.old }}` -> `{{ item.new }}`).
+  when: "item.old in vars"
+  with_items:
+    - {'old': 'matrix_media_repo_access_tokens', 'new': '<flattened into multiple matrix_media_repo_access_tokens_XXX variables - see roles/custom/matrix-media-repo/defaults/main.yml>'}
+    - {'old': 'matrix_media_repo_datastores', 'new': 'flattened into matrix_media_repo_datastores_XXX variables - see roles/custom/matrix-media-repo/defaults/main.yml'}
+    - {'old': 'matrix_media_repo_uploads', 'new': 'flattened into multiple matrix_media_repo_uploads_XXX variables - see roles/custom/matrix-media-repo/defaults/main.yml'}
+    - {'old': 'matrix_media_repo_downloads_cache_enabled', 'new': '<removed>'}
+    - {'old': 'matrix_media_repo_downloads_cache_max_size_bytes', 'new': '<removed>'}
+    - {'old': 'matrix_media_repo_downloads_cache_max_file_size_bytes', 'new': '<removed>'}
+    - {'old': 'matrix_media_repo_downloads_cache_tracked_minutes', 'new': '<removed>'}
+    - {'old': 'matrix_media_repo_downloads_cache_min_downloads', 'new': '<removed>'}
+    - {'old': 'matrix_media_repo_downloads_cache_min_cache_time_seconds', 'new': '<removed>'}
+    - {'old': 'matrix_media_repo_downloads_cache_min_evicted_time_seconds', 'new': '<removed>'}
+    - {'old': 'matrix_media_repo_url_previews', 'new': 'flattened into multiple matrix_media_repo_url_previews_XXX variables - see roles/custom/matrix-media-repo/defaults/main.yml'}
+    - {'old': 'matrix_media_repo_thumbnails', 'new': 'flattened into multiple matrix_media_repo_thumbnails_XXX variables - see roles/custom/matrix-media-repo/defaults/main.yml'}
+    - {'old': 'matrix_media_repo_feature_support', 'new': '<removed>'}