From 7f56ca85d6dba3d51974cbf7a44fdb7a7cf87881 Mon Sep 17 00:00:00 2001
From: Brice <13542296+briceholland@users.noreply.github.com>
Date: Thu, 6 Nov 2025 07:56:38 -0800
Subject: [PATCH] Enhance instructions for increasing storage capacity (#57819)

Co-authored-by: Sophie <29382425+sophietheking@users.noreply.github.com>
---
 .../increasing-storage-capacity.md            | 44 +++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-storage-capacity.md b/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-storage-capacity.md
index ab3af4b21c..6ac3bbd6c1 100644
--- a/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-storage-capacity.md
+++ b/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-storage-capacity.md
@@ -54,6 +54,50 @@ Root storage refers to the total size of your instance's root disk. The availabl
 
 1. Ensure system services are functioning correctly, then release maintenance mode. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode).
 
+> [!WARNING]
+> If the `ghe-storage-extend` command (or a prior automatic check) reports: `ghe_user_data contains a file system with errors`, you must repair the filesystem before retrying the resize. Do not rerun `ghe-storage-extend` until the check completes cleanly. For recovery instructions, see [Repairing filesystem errors](#repairing-filesystem-errors).
+
+### Repairing filesystem errors
+
+If the filesystem check fails during `ghe-storage-extend`, follow these steps to repair it.
+
+Ensure the appliance is in maintenance mode and no background jobs are running:
+
+   ```shell copy
+   ghe-maintenance -s
+   ghe-resque-info
+   ```
+
+1. Stop and activate the user volume, then run a forced filesystem check (auto‑answer yes):
+
+   ```shell copy
+   sudo systemctl stop ghe-user-disk
+   VGNAME=$(sudo lvs --noheadings -o vg_name | grep ghe_storage_ | awk '{ print $1 }')
+   sudo vgchange -ay "$VGNAME"
+   sudo vgscan --mknodes
+   sudo fsck -fy /dev/mapper/${VGNAME}-ghe_user_data
+   ```
+
+1. Retry the resize:
+
+   ```shell copy
+   ghe-storage-extend
+   ```
+
+1. Remount and verify new size:
+
+   ```shell copy
+   sudo systemctl start ghe-user-disk
+   df -h /data/user
+   ```
+
+1. Reboot and verify:
+
+   ```shell copy
+   sudo reboot
+   df -h /data/user
+   ```
+
 ## Increasing the root partition size using a new appliance
 
 1. Set up a new {% data variables.product.prodname_ghe_server %} instance with a larger root disk using the same version as your current appliance. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance).