From f4c64aa20e7f96804f541755e426f74c531bdb4d Mon Sep 17 00:00:00 2001 From: Daria Staferova Date: Mon, 16 Feb 2026 16:03:05 +0200 Subject: [PATCH 1/5] Add health endpoint to endpoints env var document --- docs/hosting/configuration/environment-variables/endpoints.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/hosting/configuration/environment-variables/endpoints.md b/docs/hosting/configuration/environment-variables/endpoints.md index 234dfee3d92..26e09547afc 100644 --- a/docs/hosting/configuration/environment-variables/endpoints.md +++ b/docs/hosting/configuration/environment-variables/endpoints.md @@ -37,5 +37,6 @@ This page lists environment variables for customizing endpoints in n8n. | `N8N_ENDPOINT_WEBHOOK` | String | `webhook` | The path used for webhook endpoint. | | `N8N_ENDPOINT_WEBHOOK_TEST` | String | `webhook-test` | The path used for test-webhook endpoint. | | `N8N_ENDPOINT_WEBHOOK_WAIT` | String | `webhook-waiting` | The path used for waiting-webhook endpoint. | +| `N8N_ENDPOINT_HEALTH` | String | `healthz` | The path used for health check endpoint. | | `WEBHOOK_URL` | String | - | Used to manually provide the Webhook URL when running n8n behind a reverse proxy. See [here](/hosting/configuration/configuration-examples/webhook-url.md) for more details. | | `N8N_DISABLE_PRODUCTION_MAIN_PROCESS` | Boolean | `false` | Disable production webhooks from main process. This helps ensure no HTTP traffic load to main process when using webhook-specific processes. | From 8df175eae2cf4bcc33056d09e93867df74bbfcac Mon Sep 17 00:00:00 2001 From: Daria Staferova Date: Mon, 16 Feb 2026 16:05:29 +0200 Subject: [PATCH 2/5] Add info about custom health endpoint to Google Cloud Run document --- .../installation/server-setups/google-cloud-run.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/hosting/installation/server-setups/google-cloud-run.md b/docs/hosting/installation/server-setups/google-cloud-run.md index 31544ca801e..1f35af5baa2 100644 --- a/docs/hosting/installation/server-setups/google-cloud-run.md +++ b/docs/hosting/installation/server-setups/google-cloud-run.md @@ -38,6 +38,10 @@ You can also explicitly enable the Cloud Run API (even if you don't do this, it gcloud services enable run.googleapis.com ``` +/// warning | Required: Custom health check endpoint +Google Cloud Run reserves `/healthz` for its own health checks. Since n8n uses this path by default, it can conflict and cause connection issues in the workflow canvas. To fix this, set the `N8N_ENDPOINT_HEALTH` environment variable to a custom path (included in the deployment commands below). +/// + To deploy n8n: ```sh @@ -47,7 +51,8 @@ gcloud run deploy n8n \ --allow-unauthenticated \ --port=5678 \ --no-cpu-throttling \ - --memory=2Gi + --memory=2Gi \ + --set-env-vars="N8N_ENDPOINT_HEALTH=health" ``` (you can specify whichever region you prefer, instead of "us-west1") @@ -64,7 +69,8 @@ gcloud run deploy n8n \ --port=5678 \ --no-cpu-throttling \ --memory=2Gi \ - --scaling=1 + --scaling=1 \ + --set-env-vars="N8N_ENDPOINT_HEALTH=health" ``` This does not prevent data loss completely, such as whenever the Cloud Run service is re-deployed/updated. If you want truly persistant data, you should refer to the instructions below for how to attach a database. @@ -190,7 +196,7 @@ gcloud run deploy n8n \ --port=5678 \ --memory=2Gi \ --no-cpu-throttling \ - --set-env-vars="N8N_PORT=5678,N8N_PROTOCOL=https,DB_TYPE=postgresdb,DB_POSTGRESDB_DATABASE=n8n,DB_POSTGRESDB_USER=n8n-user,DB_POSTGRESDB_HOST=/cloudsql/$PROJECT_ID:$REGION:n8n-db,DB_POSTGRESDB_PORT=5432,DB_POSTGRESDB_SCHEMA=public,GENERIC_TIMEZONE=UTC,QUEUE_HEALTH_CHECK_ACTIVE=true" \ + --set-env-vars="N8N_PORT=5678,N8N_PROTOCOL=https,N8N_ENDPOINT_HEALTH=health,DB_TYPE=postgresdb,DB_POSTGRESDB_DATABASE=n8n,DB_POSTGRESDB_USER=n8n-user,DB_POSTGRESDB_HOST=/cloudsql/$PROJECT_ID:$REGION:n8n-db,DB_POSTGRESDB_PORT=5432,DB_POSTGRESDB_SCHEMA=public,GENERIC_TIMEZONE=UTC,QUEUE_HEALTH_CHECK_ACTIVE=true" \ --set-secrets="DB_POSTGRESDB_PASSWORD=n8n-db-password:latest,N8N_ENCRYPTION_KEY=n8n-encryption-key:latest" \ --add-cloudsql-instances=$PROJECT_ID:$REGION:n8n-db \ --service-account=n8n-service-account@$PROJECT_ID.iam.gserviceaccount.com From 2fe1e7588cae5d954b25ae5388f635a5e86213e5 Mon Sep 17 00:00:00 2001 From: Daria Staferova Date: Mon, 16 Feb 2026 17:23:40 +0200 Subject: [PATCH 3/5] Add info about custom health endpoint to Monitoring and Queue mode --- docs/hosting/logging-monitoring/monitoring.md | 11 +++++++++-- docs/hosting/scaling/queue-mode.md | 4 ++++ 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/hosting/logging-monitoring/monitoring.md b/docs/hosting/logging-monitoring/monitoring.md index 2ae2673b00f..fb53e582339 100644 --- a/docs/hosting/logging-monitoring/monitoring.md +++ b/docs/hosting/logging-monitoring/monitoring.md @@ -40,10 +40,17 @@ Access the endpoint: /// info | Feature availability The `/metrics` endpoint isn't available on n8n Cloud. /// + +## Customizing the health check endpoint + +You can customize the health check endpoint path using the `N8N_ENDPOINT_HEALTH` [environment variable](/hosting/configuration/environment-variables/endpoints.md). + -## Enable metrics and healthz for self-hosted n8n +## Enable metrics and health checks for self-hosted n8n -The `/metrics` and `/healthz` endpoints are disabled by default. To enable them, configure your n8n instance: +The `/metrics` endpoint is disabled by default. For the main n8n server, the health endpoint is always enabled. However, for worker servers in [queue mode](/hosting/scaling/queue-mode.md), the `/healthz` endpoint is disabled by default. + +To enable them, configure your n8n instance: ```shell # metrics diff --git a/docs/hosting/scaling/queue-mode.md b/docs/hosting/scaling/queue-mode.md index 7c8dba2da3a..f9f3949caa3 100644 --- a/docs/hosting/scaling/queue-mode.md +++ b/docs/hosting/scaling/queue-mode.md @@ -123,6 +123,10 @@ Each worker process runs a server that exposes optional endpoints: - [credentials overwrite endpoint](/embed/configuration.md#credential-overwrites) - [`/metrics`](/hosting/configuration/configuration-examples/prometheus.md) +/// note | Customizing health check endpoints +You can customize the health check endpoint path using the [`N8N_ENDPOINT_HEALTH`](/hosting/configuration/environment-variables/endpoints.md) environment variable. +/// + #### View running workers /// info | Feature availability From 90ea1b3590c815bc6aada1046f865642c0c246c5 Mon Sep 17 00:00:00 2001 From: Daria Staferova Date: Mon, 16 Feb 2026 17:26:52 +0200 Subject: [PATCH 4/5] Improve wording --- docs/hosting/logging-monitoring/monitoring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hosting/logging-monitoring/monitoring.md b/docs/hosting/logging-monitoring/monitoring.md index fb53e582339..b9565e40e6a 100644 --- a/docs/hosting/logging-monitoring/monitoring.md +++ b/docs/hosting/logging-monitoring/monitoring.md @@ -48,7 +48,7 @@ You can customize the health check endpoint path using the `N8N_ENDPOINT_HEALTH` ## Enable metrics and health checks for self-hosted n8n -The `/metrics` endpoint is disabled by default. For the main n8n server, the health endpoint is always enabled. However, for worker servers in [queue mode](/hosting/scaling/queue-mode.md), the `/healthz` endpoint is disabled by default. +The `/metrics` endpoint is disabled by default. The health endpoint is always enabled on the main n8n server. For worker servers in [queue mode](/hosting/scaling/queue-mode.md), the health endpoint is disabled by default. To enable them, configure your n8n instance: From 5a6c79e3b3ea62bcb5bf8c1cf2113394d2538aa0 Mon Sep 17 00:00:00 2001 From: Daria Staferova Date: Mon, 16 Feb 2026 17:41:25 +0200 Subject: [PATCH 5/5] Switch to using a note in Monitoring --- docs/hosting/logging-monitoring/monitoring.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/hosting/logging-monitoring/monitoring.md b/docs/hosting/logging-monitoring/monitoring.md index b9565e40e6a..efb1901f298 100644 --- a/docs/hosting/logging-monitoring/monitoring.md +++ b/docs/hosting/logging-monitoring/monitoring.md @@ -26,6 +26,9 @@ Access the endpoint: /healthz/readiness ``` +/// note | Customizing health check endpoints +You can customize the health check endpoint path using the [`N8N_ENDPOINT_HEALTH`](/hosting/configuration/environment-variables/endpoints.md) environment variable. +/// ## metrics @@ -41,10 +44,6 @@ Access the endpoint: The `/metrics` endpoint isn't available on n8n Cloud. /// -## Customizing the health check endpoint - -You can customize the health check endpoint path using the `N8N_ENDPOINT_HEALTH` [environment variable](/hosting/configuration/environment-variables/endpoints.md). - ## Enable metrics and health checks for self-hosted n8n