diff --git a/server/storage/data/generate/im_filemsglinks_msgid_bigint.sql b/server/storage/data/generate/im_filemsglinks_msgid_bigint.sql
new file mode 100644
index 0000000..c332060
--- /dev/null
+++ b/server/storage/data/generate/im_filemsglinks_msgid_bigint.sql
@@ -0,0 +1,15 @@
+-- im_filemsglinks.msgid: INT -> BIGINT
+--
+-- Background: message ids are snowflake int64 values (~1.58e18). The msgid
+-- column was INT (max 2147483647), so every attempt to insert a message-file
+-- link failed with MySQL error 1264 "Out of range value for column 'msgid'".
+-- The failing Kafka message-persist consumer then retried the same message
+-- forever, stalling its partition and blocking persistence for every message
+-- queued behind it (p2p history stuck at old seqs while senders' seq kept
+-- advancing in Redis).
+--
+-- Applies to: any environment provisioned before 2026-10-13. im_filemsglinks
+-- is a global (non tenant-sharded) table, so a single statement per DB is
+-- enough. Verified online on the test env (table is small).
+
+ALTER TABLE im_filemsglinks MODIFY msgid BIGINT DEFAULT NULL;