diff --git a/charts/jellyfin/Chart.yaml b/charts/jellyfin/Chart.yaml
index 169912d..d487790 100644
--- a/charts/jellyfin/Chart.yaml
+++ b/charts/jellyfin/Chart.yaml
@@ -21,6 +21,7 @@ annotations:
       links:
         - name: Documentation
           url: https://kubernetes.io/docs/concepts/services-networking/network-policies/
+      description: Add troubleshooting documentation for inotify instance limits with workaround example
     - kind: added
       description: Add support for Gateway API HTTPRoute resource
     - kind: added
diff --git a/charts/jellyfin/README.md b/charts/jellyfin/README.md
index 5d9ca99..69bd948 100644
--- a/charts/jellyfin/README.md
+++ b/charts/jellyfin/README.md
@@ -424,6 +424,46 @@ networkPolicy:
 - Either disable NetworkPolicy or disable host networking
 
 For more configuration options, see the full values documentation in [values.yaml](values.yaml).
+## Troubleshooting
+
+### inotify Instance Limit Reached
+
+**Problem:** Jellyfin crashes with error:
+```
+System.IO.IOException: The configured user limit (128) on the number of inotify instances has been reached
+```
+
+**Root cause:** The Linux kernel has a limit on inotify instances (file system watchers) per user. Jellyfin uses inotify to monitor media libraries for changes.
+
+**Proper solution (recommended):**
+
+Increase the inotify limit on the Kubernetes nodes:
+
+```bash
+# Temporary (until reboot)
+sysctl -w fs.inotify.max_user_instances=512
+
+# Permanent
+echo "fs.inotify.max_user_instances=512" >> /etc/sysctl.conf
+sysctl -p
+```
+
+Recommended values:
+- `fs.inotify.max_user_instances`: 512 or higher
+- `fs.inotify.max_user_watches`: 524288 or higher (if you have large media libraries)
+
+**Workaround (if you cannot modify host settings):**
+
+If you're running on a managed Kubernetes cluster where you cannot modify node-level settings, you can force Jellyfin to use polling instead of inotify. **Note: This is less efficient and may increase CPU usage and delay change detection.**
+
+```yaml
+jellyfin:
+  env:
+    - name: DOTNET_USE_POLLING_FILE_WATCHER
+      value: "1"
+```
+
+This workaround disables inotify file watching in favor of periodic polling, which doesn't require inotify instances but is less efficient.
 
 ## IPv6 Configuration
 
diff --git a/charts/jellyfin/README.md.gotmpl b/charts/jellyfin/README.md.gotmpl
index a61d38d..fa63b7c 100644
--- a/charts/jellyfin/README.md.gotmpl
+++ b/charts/jellyfin/README.md.gotmpl
@@ -313,6 +313,46 @@ networkPolicy:
 - Either disable NetworkPolicy or disable host networking
 
 For more configuration options, see the full values documentation in [values.yaml](values.yaml).
+## Troubleshooting
+
+### inotify Instance Limit Reached
+
+**Problem:** Jellyfin crashes with error:
+```
+System.IO.IOException: The configured user limit (128) on the number of inotify instances has been reached
+```
+
+**Root cause:** The Linux kernel has a limit on inotify instances (file system watchers) per user. Jellyfin uses inotify to monitor media libraries for changes.
+
+**Proper solution (recommended):**
+
+Increase the inotify limit on the Kubernetes nodes:
+
+```bash
+# Temporary (until reboot)
+sysctl -w fs.inotify.max_user_instances=512
+
+# Permanent
+echo "fs.inotify.max_user_instances=512" >> /etc/sysctl.conf
+sysctl -p
+```
+
+Recommended values:
+- `fs.inotify.max_user_instances`: 512 or higher
+- `fs.inotify.max_user_watches`: 524288 or higher (if you have large media libraries)
+
+**Workaround (if you cannot modify host settings):**
+
+If you're running on a managed Kubernetes cluster where you cannot modify node-level settings, you can force Jellyfin to use polling instead of inotify. **Note: This is less efficient and may increase CPU usage and delay change detection.**
+
+```yaml
+jellyfin:
+  env:
+    - name: DOTNET_USE_POLLING_FILE_WATCHER
+      value: "1"
+```
+
+This workaround disables inotify file watching in favor of periodic polling, which doesn't require inotify instances but is less efficient.
 
 ## IPv6 Configuration
 
diff --git a/charts/jellyfin/templates/NOTES.txt b/charts/jellyfin/templates/NOTES.txt
index d0f3435..900215c 100644
--- a/charts/jellyfin/templates/NOTES.txt
+++ b/charts/jellyfin/templates/NOTES.txt
@@ -211,6 +211,14 @@ Network Policy is ENABLED:
 Network Policy is DISABLED (default).
 To enable network isolation, set networkPolicy.enabled=true in your values.
 {{- end }}
+For troubleshooting common issues, see the README:
+- inotify instance limit errors
+- Hardware acceleration setup
+- Network configuration
+
+Useful resources:
+  Documentation: https://jellyfin.org/docs/
+  Troubleshooting: See README.md in the chart repository
 
 {{- if .Values.jellyfin.envFrom }}
 
diff --git a/charts/jellyfin/values.yaml b/charts/jellyfin/values.yaml
index 86a52d4..ac15613 100644
--- a/charts/jellyfin/values.yaml
+++ b/charts/jellyfin/values.yaml
@@ -253,11 +253,14 @@ jellyfin:
   #       name: jellyfin-secrets
   envFrom: []
   # -- Additional environment variables for the container.
+  # Example: Workaround for inotify limits (see Troubleshooting section in README)
   # Example:
   # env:
   #   - name: JELLYFIN_CACHE_DIR
   #     value: /cache
   env: []
+  # - name: DOTNET_USE_POLLING_FILE_WATCHER
+  #   value: "1"
 
 persistence:
   config: