Health Checks

Relevant source files

The following files were used as context for generating this wiki page:

• packages/@n8n/task-runner/src/health-check-server.ts
• packages/@n8n/task-runner-python/src/health_check_server.py
• packages/cli/test/integration/healthcheck.controller.test.ts
• packages/cli/src/controllers/Healthcheck.controller.ts
• packages/cli/src/config/healthcheck.ts
• packages/cli/src/services/Healthcheck.service.ts

The n8n application provides health check endpoints to monitor the status of its core components. This is essential for production deployments, especially in containerized environments like Docker and Kubernetes, where orchestrators rely on health probes to manage application lifecycle (e.g., liveness and readiness probes). The system features distinct health check mechanisms for the main n8n application and for the separate task runners.

Main Application Health Check

The main n8n application, managed by the cli package, exposes a dedicated health check endpoint. This endpoint is primarily used to verify the application's core dependencies, such as its database connection.

Sources: packages/cli/src/controllers/Healthcheck.controller.ts, packages/cli/src/services/Healthcheck.service.ts, packages/cli/src/config/healthcheck.ts

Endpoint and Controller

The health check is implemented as a NestJS controller that exposes a GET endpoint.

Property	Value
Endpoint	/healthz
Controller	HealthcheckController
Method	getHealth()
Source	packages/cli/src/controllers/Healthcheck.controller.ts:18-21

The getHealth method in the controller delegates the actual health check logic to the HealthcheckService.

Sources: packages/cli/src/controllers/Healthcheck.controller.ts:20

Service and Indicators

The HealthcheckService utilizes the @nestjs/terminus library to perform checks. The primary check implemented is for the database connection, using TypeOrmHealthIndicator to ping the database.

// packages/cli/src/services/Healthcheck.service.ts:16-18
@Injectable()
export class HealthcheckService {
	constructor(
		private readonly health: HealthCheckService,
		private readonly db: TypeOrmHealthIndicator,
	) {}

	check(): Promise<HealthCheckResult> {
		return this.health.check([() => this.db.pingCheck('database')]);
	}
}

Sources: packages/cli/src/services/Healthcheck.service.ts:16-26

Flow Diagram

The following diagram illustrates the request flow for the main application's health check.

Configuration

The health check endpoint can be configured via the healthcheck object.

Option	Type	Description	Default Value	Source File
enabled	boolean	Enables or disables the health check endpoint.	true	packages/cli/src/config/healthcheck.ts:11
port	number	The port on which the health check server listens.	5678	packages/cli/src/config/healthcheck.ts:15
endpoint	string	The path for the health check endpoint.	'/healthz'	packages/cli/src/config/healthcheck.ts:19

Sources: packages/cli/src/config/healthcheck.ts:7-21

Task Runner Health Checks

The TypeScript and Python task runners run as separate processes and expose their own simple HTTP servers for health checks. These are designed to be lightweight and are intended for use as liveness/readiness probes by container orchestrators.

TypeScript Task Runner

The @n8n/task-runner package includes a function to start a basic health check server.

• Implementation: A standard Node.js http server.
• Function: startHealthCheckServer()
• Port: Configured via the N8N_HEALTH_CHECK_PORT environment variable.
• Response: Responds to any request with HTTP status 200 and a body of "OK".

// packages/@n8n/task-runner/src/health-check-server.ts:8-15
export function startHealthCheckServer(port: number) {
	const server = http.createServer((req, res) => {
		res.writeHead(200, { 'Content-Type': 'text/plain' });
		res.end('OK');
	});

	server.listen(port, () => {
		Logger.info(`Health check server listening on port ${port}`);
	});
}

Sources: packages/@n8n/task-runner/src/health-check-server.ts:8-18

Python Task Runner

Similarly, the @n8n/task-runner-python package implements a health check server using Python's built-in http.server.

• Implementation: A ThreadingHTTPServer with a custom HealthCheckHandler.
• Port: Configured via the N8N_HEALTH_CHECK_PORT environment variable.
• Response: The do_GET method handles requests, sending a 200 OK response with the body b"OK".

# packages/@n8n/task-runner-python/src/health_check_server.py:10-14
class HealthCheckHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.end_headers()
        self.wfile.write(b"OK")

Sources: packages/@n8n/task-runner-python/src/health_check_server.py:10-14

Flow Diagram for Task Runners

This diagram shows the simple health check process for both task runners.

Testing

The health check functionality is validated through integration tests. The test for the main application's health check uses supertest to send a request to the /healthz endpoint and asserts the expected response.

A successful health check returns a 200 status code and a JSON body indicating the status of checked components.

// packages/cli/test/integration/healthcheck.controller.test.ts:34-41
it('should return 200 OK and health status', async () => {
    const response = await request(app.getHttpServer()).get('/healthz');

    expect(response.status).toBe(200);
    expect(response.body).toEqual({
        status: 'ok',
        info: { database: { status: 'up' } },
        error: {},
        details: { database: { status: 'up' } },
    });
});

This test confirms that the endpoint is reachable and that the database check reports an 'up' status.

Sources: packages/cli/test/integration/healthcheck.controller.test.ts:34-41

Summary

n8n provides a robust and decoupled health check system. The main application offers a detailed health status via the /healthz endpoint, focusing on critical dependencies like the database. Concurrently, the individual task runners expose simple, independent health endpoints suitable for high-frequency liveness probes. This separation allows for precise monitoring and management of each component within a modern, containerized infrastructure.