From 4a45dc998a98113b06b1db0bd82eb4d14e8790c7 Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Wed, 5 Nov 2025 23:32:38 +0300 Subject: [PATCH 1/2] docs(troubleshooting): add inotify limits documentation and workaround Add comprehensive troubleshooting documentation for inotify instance limit errors that cause Jellyfin crashes in environments with many containers. Changes: - Add Troubleshooting section to README with inotify limits explanation - Document proper solution: increase kernel limits via sysctl - Provide workaround for managed clusters: DOTNET_USE_POLLING_FILE_WATCHER - Add commented example in values.yaml for easy copy-paste - Update Chart version from 2.5.0 to 2.5.1 - Add Artifact Hub changelog annotation The proper solution is to increase inotify limits on Kubernetes nodes: ```bash sysctl -w fs.inotify.max_user_instances=512 ``` For managed Kubernetes where node access is restricted, users can use the polling workaround (less efficient but functional): ```yaml jellyfin: env: - name: DOTNET_USE_POLLING_FILE_WATCHER value: "1" ``` This addresses the crash issue mentioned in #64. Fixes: #64 Co-Authored-By: Claude Signed-off-by: Aleksei Sviridkin --- charts/jellyfin/Chart.yaml | 6 ++++- charts/jellyfin/README.md | 45 ++++++++++++++++++++++++++++++-- charts/jellyfin/README.md.gotmpl | 41 +++++++++++++++++++++++++++++ charts/jellyfin/values.yaml | 3 +++ 4 files changed, 92 insertions(+), 3 deletions(-) diff --git a/charts/jellyfin/Chart.yaml b/charts/jellyfin/Chart.yaml index 96a351b..47ccd67 100644 --- a/charts/jellyfin/Chart.yaml +++ b/charts/jellyfin/Chart.yaml @@ -8,5 +8,9 @@ keywords: - jellyfin - media - self-hosted -version: 2.5.0 +version: 2.5.1 appVersion: 10.11.2 +annotations: + artifacthub.io/changes: | + - kind: added + description: Add troubleshooting documentation for inotify instance limits with workaround example diff --git a/charts/jellyfin/README.md b/charts/jellyfin/README.md index 10952b6..bbb9875 100644 --- a/charts/jellyfin/README.md +++ b/charts/jellyfin/README.md @@ -1,6 +1,6 @@ # jellyfin -![Version: 2.5.0](https://img.shields.io/badge/Version-2.5.0-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 10.11.2](https://img.shields.io/badge/AppVersion-10.11.2-informational?style=flat-square) +![Version: 2.5.1](https://img.shields.io/badge/Version-2.5.1-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 10.11.2](https://img.shields.io/badge/AppVersion-10.11.2-informational?style=flat-square) A Helm chart for Jellyfin Media Server @@ -68,7 +68,7 @@ helm install my-jellyfin jellyfin/jellyfin -f values.yaml | jellyfin.args | list | `[]` | Additional arguments for the entrypoint command. | | jellyfin.command | list | `[]` | Custom command to use as container entrypoint. | | jellyfin.enableDLNA | bool | `false` | Enable DLNA. Requires host network. See: https://jellyfin.org/docs/general/networking/dlna.html | -| jellyfin.env | list | `[]` | Additional environment variables for the container. | +| jellyfin.env | list | `[]` | Additional environment variables for the container. Example: Workaround for inotify limits (see Troubleshooting section in README) | | livenessProbe | object | `{"initialDelaySeconds":10,"tcpSocket":{"port":"http"}}` | Configure liveness probe for Jellyfin. | | metrics | object | `{"enabled":false,"serviceMonitor":{"enabled":false,"interval":"30s","labels":{},"metricRelabelings":[],"namespace":"","path":"/metrics","port":8096,"relabelings":[],"scheme":"http","scrapeTimeout":"30s","targetLabels":[],"tlsConfig":{}}}` | Configuration for metrics collection and monitoring | | metrics.enabled | bool | `false` | Enable or disable metrics collection | @@ -160,3 +160,44 @@ extraVolumeMounts: - name: hwa mountPath: /dev/dri ``` + +## 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. diff --git a/charts/jellyfin/README.md.gotmpl b/charts/jellyfin/README.md.gotmpl index ee08a35..d0d5f30 100644 --- a/charts/jellyfin/README.md.gotmpl +++ b/charts/jellyfin/README.md.gotmpl @@ -85,3 +85,44 @@ extraVolumeMounts: - name: hwa mountPath: /dev/dri ``` + +## 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. diff --git a/charts/jellyfin/values.yaml b/charts/jellyfin/values.yaml index 068c0ef..103122f 100644 --- a/charts/jellyfin/values.yaml +++ b/charts/jellyfin/values.yaml @@ -192,7 +192,10 @@ jellyfin: # -- Additional arguments for the entrypoint command. args: [] # -- Additional environment variables for the container. + # Example: Workaround for inotify limits (see Troubleshooting section in README) env: [] + # - name: DOTNET_USE_POLLING_FILE_WATCHER + # value: "1" persistence: config: From 4bdedb2c21e65e9e3bbc868fd49a501b4eb5d0de Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Fri, 7 Nov 2025 19:55:17 +0300 Subject: [PATCH 2/2] docs(notes): add deployment notes with troubleshooting references Add NOTES.txt with: - Basic access instructions (Ingress or port-forward) - Reference to troubleshooting documentation in README - Links to Jellyfin documentation This complements the inotify troubleshooting documentation added in README.md.gotmpl, making users aware of available resources. Co-Authored-By: Claude Signed-off-by: Aleksei Sviridkin --- charts/jellyfin/templates/NOTES.txt | 32 +++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 charts/jellyfin/templates/NOTES.txt diff --git a/charts/jellyfin/templates/NOTES.txt b/charts/jellyfin/templates/NOTES.txt new file mode 100644 index 0000000..7cc6fdf --- /dev/null +++ b/charts/jellyfin/templates/NOTES.txt @@ -0,0 +1,32 @@ +Thank you for installing {{ .Chart.Name }}. + +Your release is named {{ .Release.Name }}. + +To learn more about the release, try: + + $ helm status {{ .Release.Name }} + $ helm get all {{ .Release.Name }} + +{{- if .Values.ingress.enabled }} + +Jellyfin is available via Ingress at: +{{- range .Values.ingress.hosts }} + http{{ if $.Values.ingress.tls }}s{{ end }}://{{ .host }}{{ (index .paths 0).path }} +{{- end }} +{{- else }} + +To access Jellyfin, you can use port-forwarding: + + $ kubectl port-forward --namespace {{ .Release.Namespace }} svc/{{ include "jellyfin.fullname" . }} {{ .Values.service.port }}:{{ .Values.service.port }} + +Then visit http://localhost:{{ .Values.service.port }} in your browser. +{{- 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