n8n User Guide

1. Quick Start

n8n is a source-available workflow automation platform that lets you connect hundreds of services, build complex automations through a visual node-based editor, and run them on your own infrastructure. It supports everything from simple two-step integrations to sophisticated AI-powered agent workflows with branching logic, error handling, and human-in-the-loop patterns.

Key features:

• Visual workflow editor with drag-and-drop node canvas
• 400+ built-in integration nodes (Google, Slack, GitHub, databases, HTTP, and more)
• Code nodes for custom JavaScript and Python logic
• AI agent capabilities with LLM integration (OpenAI, Anthropic, Google, xAI)
• Webhook triggers for real-time event processing
• Cron/schedule-based workflow execution
• Self-hosted with full data control
• Multi-user collaboration with role-based access control
• Version history and source control integration

Prerequisites:

• Node.js >= 22.16 (for source install) or Docker
• 2+ GB RAM recommended

Fastest way to start:

docker run -it --rm --name n8n -p 5678:5678 -v n8n_data:/home/node/.n8n ghcr.io/n8n-io/n8n

n8n ready on 0.0.0.0, port 5678

Open http://localhost:5678 in your browser to access the workflow editor.

Tip

For a quick test without persistent data, omit the -v flag. For production use, always mount a volume to preserve workflows and credentials across container restarts.

What to try next:

• Create your first workflow in the visual editor
• Browse the node panel to discover available integrations
• Set up a webhook trigger to receive external events
• See the Configuration section for environment variables
• See the Admin Guide for deployment, scaling, and security

2. Installation

System Requirements

Installation Methods

Docker (Recommended)

docker run -it --rm --name n8n \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  ghcr.io/n8n-io/n8n

Docker Compose

services:
  n8n:
    image: ghcr.io/n8n-io/n8n
    ports:
      - "5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n
    environment:
      - N8N_HOST=localhost
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
volumes:
  n8n_data:

docker compose up -d

npm

npm install -g n8n
n8n start

npx

npx n8n

Source

git clone https://github.com/n8n-io/n8n.git
cd n8n
pnpm install
pnpm build
pnpm start

Important

Source builds require pnpm >= 10.22.0 and Node.js >= 22.16. The monorepo uses Turborepo for orchestrated builds across ~40 packages.

Post-Install Verification

After starting n8n, verify it is running:

curl http://localhost:5678/healthz

{"status":"ok"}

Open http://localhost:5678 in your browser. On first launch, you will be prompted to create an owner account with email and password.

Custom SSL Certificates (Docker)

To trust custom or corporate CA certificates in the Docker container, mount them into /opt/custom-certificates:

docker run -it --rm --name n8n \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  -v /path/to/certs:/opt/custom-certificates \
  ghcr.io/n8n-io/n8n

The entrypoint script automatically detects this directory, sets NODE_OPTIONS="--use-openssl-ca" and SSL_CERT_DIR=/opt/custom-certificates, and runs c_rehash.

Warning

If you are behind a corporate proxy, you may also need to set HTTP_PROXY and HTTPS_PROXY environment variables. n8n supports proxy configuration via standard environment variables (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY).

Installation Troubleshooting

Error: port 5678 is already in use

Cause: Another process is using port 5678.

Solution:

1. Change the port: N8N_PORT=5679 n8n start
2. Or find and stop the conflicting process

Prevention: Use a dedicated port or run in Docker with port mapping.

Error: SQLITE_CANTOPEN

Cause: n8n cannot write to its data directory.

Solution:

1. Check permissions on ~/.n8n/ directory
2. Set a custom path: N8N_USER_FOLDER=/path/to/writable/dir

Error: Node.js version mismatch

Cause: n8n requires Node.js >= 22.16.

Solution:

1. Update Node.js: nvm install 22
2. Or use Docker (includes the correct Node.js version)

Error: pnpm not found (source install)

Cause: pnpm is not installed or wrong version.

Solution:

corepack enable
corepack prepare pnpm@10.32.1 --activate

3. Configuration

n8n is configured primarily through environment variables. All environment variables support a _FILE suffix to read values from a file (useful for Docker secrets).

Essential Environment Variables

Important

The N8N_ENCRYPTION_KEY is critical. If lost, all stored credentials become unreadable. Back it up securely. In multi-instance (queue mode) setups, all instances must share the same encryption key.

Database Configuration

Tip

SQLite is fine for personal use and small teams. For production with multiple users, high-volume workflows, or queue mode, use PostgreSQL.

SSL/HTTPS Configuration

Proxy Configuration

Webhook Configuration

Code Node Security

Warning

Allowing built-in modules like fs, child_process, or net in Code nodes grants workflows access to the host filesystem and network. Only allow what is strictly necessary.

For the complete configuration reference including all environment variables, deployment modes, and scaling options, see the Admin Guide.

4. Core Usage

The Workflow Editor

The n8n editor is a visual canvas where you build workflows by connecting nodes. Each node represents an action — fetching data, transforming it, sending it somewhere, or making a decision.

Key concepts:

• Workflow — A directed graph of connected nodes that executes from left to right
• Node — A single unit of work (trigger, action, or logic)
• Connection — A link between nodes that passes data
• Execution — A single run of a workflow
• Trigger — The starting node that initiates a workflow (webhook, schedule, manual, etc.)
• Pinned data — Sample data attached to a node for testing without triggering real events

Node Types

Building Your First Workflow

1. Open the editor at http://localhost:5678
2. Click Add first step or the + button on the canvas
3. Select a trigger node (e.g., Manual Trigger for testing)
4. Add action nodes by clicking + on the right side of a node
5. Configure each node's parameters in the Node Detail View (NDV)
6. Click Test workflow to run with test data
7. Toggle Active to enable automatic execution

Tip

Use Pin data on any node to freeze its output for testing downstream nodes without re-executing the entire workflow.

Expressions

n8n uses a JavaScript-based expression system to reference data from previous nodes. Expressions are enclosed in {{ }}:

// Reference output of a previous node
{{ $('Previous Node').item.json.fieldName }}

// Access the current item
{{ $json.email }}

// Use JavaScript functions
{{ $json.name.toUpperCase() }}

// Date formatting
{{ $now.format('yyyy-MM-dd') }}

// Conditional expressions
{{ $json.status === 'active' ? 'Yes' : 'No' }}

Note

The expression engine runs in a sandboxed environment with configurable memory and timeout limits. Complex expressions involving large datasets may hit these limits.

Webhooks

Webhook nodes create HTTP endpoints that trigger workflows on incoming requests:

1. Add a Webhook node as the trigger
2. Configure the HTTP method (GET, POST, PUT, DELETE, etc.)
3. Set the webhook path (e.g., /my-webhook)
4. The full URL will be: {N8N_EDITOR_BASE_URL}/webhook/{path}
5. Choose response mode:
   • Immediately — responds as soon as the webhook is received
   • When Last Node Finishes — responds with the output of the last node
   • Using Respond to Webhook Node — use a Respond to Webhook node for custom responses

Test webhooks use a separate URL path (/webhook-test/) and are only active while the editor is open.

Code Nodes

Code nodes let you write custom JavaScript or Python code:

JavaScript example:

// Process all items
for (const item of $input.all()) {
  item.json.processed = true;
  item.json.timestamp = new Date().toISOString();
}
return $input.all();

Python example:

# Process all items
for item in _input.all():
    item.json["processed"] = True
    item.json["count"] = len(item.json.get("data", []))
return _input.all()

Warning

Python Code nodes run in an external task runner with strict sandboxing. Many Python builtins (eval, exec, open, getattr, __import__) are blocked for security. Imports are restricted to explicitly allowed modules via N8N_RUNNERS_STDLIB_ALLOW and N8N_RUNNERS_EXTERNAL_ALLOW.

AI Workflows

n8n includes built-in AI capabilities for building agent-based workflows:

Available AI node categories:

Building an AI Agent workflow:

1. Add an AI Agent node
2. Connect a Chat Model sub-node (e.g., OpenAI GPT-4)
3. Add Tool sub-nodes for the agent's capabilities
4. Optionally add a Memory sub-node for conversation persistence
5. Connect a trigger (Webhook, Chat Trigger, or Manual)

Note

AI features may require a license for full functionality. The AI Gateway (feat:aiGateway) provides managed AI credentials. Free AI credits may be available for initial setup.

Forms

Form nodes create web forms that collect user input and feed it into workflows:

1. Add a Form Trigger node
2. Define form fields (text, email, number, dropdown, etc.)
3. The form URL is served at the configured webhook path
4. Submitted data flows through the workflow as JSON

5. Common Tasks

Schedule a Recurring Workflow

Goal: Run a workflow every morning at 9 AM.

1. Add a Schedule Trigger node
2. Set the trigger rule to Every Day at 09:00
3. Set GENERIC_TIMEZONE to your timezone if not already configured
4. Add your workflow logic after the trigger
5. Activate the workflow

Verify: Check the Executions tab to see scheduled runs.

If it fails: Verify the timezone setting and check that the workflow is active (toggle is green).

Send a Slack Message When a GitHub Issue Is Created

Goal: Post to Slack whenever a new issue appears.

1. Add a GitHub Trigger node → select Issues event → opened action
2. Add a Slack node → Send Message operation
3. Configure the Slack message with expressions:

   New issue: {{ $json.issue.title }}
   URL: {{ $json.issue.html_url }}
   

4. Set up credentials for both GitHub and Slack
5. Activate the workflow

Process Incoming Webhooks

Goal: Receive data from an external service and store it.

1. Add a Webhook node → set path to /incoming-data → POST method
2. Add a Set node to transform/clean the data
3. Add a database node (PostgreSQL, MySQL, etc.) to store the data
4. Test with:

   curl -X POST http://localhost:5678/webhook/incoming-data \
     -H "Content-Type: application/json" \
     -d '{"name": "test", "value": 42}'
   

5. Activate the workflow for production webhooks

Transform and Merge Data from Multiple Sources

Goal: Combine data from two APIs into a single output.

1. Add a Manual Trigger
2. Add two HTTP Request nodes (one for each API)
3. Add a Merge node → select merge mode:
   • Append — combine all items
   • Combine — match items by field
   • Choose Branch — pick one input
4. Add a Set node to reshape the merged data
5. Test the workflow

Error Handling in Workflows

Goal: Gracefully handle node failures.

1. On any node, open Settings → On Error → choose:
   • Stop Workflow (default)
   • Continue (skip the error, pass empty data)
   • Continue (Using Error Output) — route errors to a dedicated branch
2. For the error output option, connect the error output (red) to error-handling nodes
3. Use a Send Email or Slack node on the error branch to notify on failures

Tip

Use the Execute Workflow node to create reusable error-handling sub-workflows that multiple workflows can call.

Use Environment Variables in Workflows

Goal: Reference configuration values without hardcoding.

1. Define variables in Settings → Variables (or via the API)
2. Reference them in expressions: {{ $vars.MY_VARIABLE }}
3. For sensitive values, use credentials instead of variables

Export and Import Workflows

Goal: Move workflows between instances.

Export:

1. Open the workflow in the editor
2. Click the ... menu → Download
3. The workflow is saved as a JSON file

Import:

1. Go to Workflows → Import from File
2. Select the JSON file
3. Update credentials (they are not included in exports)

Use the External CLI

The @n8n/cli package provides a command-line interface to manage a running n8n instance remotely:

npx @n8n/cli login

? n8n instance URL: http://localhost:5678
? API key: ****
✓ Connected to n8n at http://localhost:5678

Common CLI commands:

# List workflows
npx @n8n/cli workflow:list

# Activate a workflow
npx @n8n/cli workflow:activate --id 123

# List executions
npx @n8n/cli execution:list --status=error

# Create a credential
npx @n8n/cli credential:create --type=slackApi --data='{"token":"xoxb-..."}'

# Pull source control changes
npx @n8n/cli source-control:pull

Note

CLI configuration is stored at ~/.n8n-cli/config.json. Connection can be set via flags (--url, --apiKey), environment variables (N8N_URL, N8N_API_KEY), or the config file.

6. Troubleshooting

Diagnostic Decision Tree

Problem?
├── Can't access the editor?
│   ├── Check n8n is running: curl http://localhost:5678/healthz
│   ├── Check the port: N8N_PORT environment variable
│   └── Check firewall/proxy settings
├── Workflow not triggering?
│   ├── Is the workflow active? (toggle must be green)
│   ├── Webhook URL correct? (production vs test URL)
│   ├── Schedule trigger timezone correct? (GENERIC_TIMEZONE)
│   └── Check execution log for errors
├── Credential errors?
│   ├── Re-authenticate the credential
│   ├── Check API key/token expiration
│   ├── Verify OAuth callback URL matches N8N_EDITOR_BASE_URL
│   └── Check proxy settings for external API access
├── Node execution errors?
│   ├── Check the error message in the execution detail
│   ├── Test with pinned data to isolate the issue
│   └── Check rate limits on external services
└── Performance issues?
    ├── Check execution concurrency limits
    ├── Consider PostgreSQL instead of SQLite
    └── See Admin Guide for scaling options

Error: OAuth2 token refresh fails behind corporate proxy

Cause: The OAuth2 client does not pass proxy settings when refreshing tokens (community issue #28225).

Solution:

1. Ensure HTTP_PROXY and HTTPS_PROXY are set in the n8n environment
2. Restart n8n after setting proxy variables
3. Re-authenticate the affected credential

Prevention: Always configure proxy environment variables before setting up OAuth credentials.

Error: Model Selector node not recognized as ChatModel

Cause: Tools Agent node validation fails when using a Model Selector node as the chat model input (community issue #18561).

Solution:

1. Connect the chat model node directly to the agent instead of through a Model Selector
2. Or update to the latest n8n version where this may be resolved

Error: MCP error

Cause: Model Context Protocol server connection failures (community issue #28046).

Solution:

1. Verify the MCP server is running and accessible
2. Check the MCP server configuration in the node settings
3. Verify network connectivity between n8n and the MCP server

Error: Debug Editor is not available in Community Plan

Cause: The debug editor feature requires an n8n license (community issue #28537).

Solution: This is expected behavior. The debug editor is an Enterprise feature. Use the standard execution view for debugging workflows.

Error: Chat Model output not accessible in subsequent nodes

Cause: AI Agent node output structure differs from regular nodes (community issue #21673).

Solution:

1. Use expressions to access the agent's output: {{ $json.output }}
2. The AI Agent returns structured output — check the Output panel for the exact data structure

Error: Binary file system not working properly

Cause: Binary data storage path is misconfigured or lacks write permissions (community issue #27836).

Solution:

1. Check N8N_BINARY_DATA_STORAGE_PATH is set to a writable directory
2. Verify filesystem permissions
3. If using Docker, ensure the volume is correctly mounted

Prevention: Always use named Docker volumes or bind mounts with correct ownership (uid/gid 1000).

Error: Workflow activation failed

Cause: A trigger node has invalid configuration, or an external service is unreachable.

Solution:

1. Open the workflow and check each trigger node for errors
2. Test credentials by re-authenticating
3. Check the Active Workflows error endpoint: GET /active-workflows/error/{workflowId}

Error: Expression evaluation failed

Cause: An expression references data that does not exist, or contains a syntax error.

Solution:

1. Check that the referenced node name matches exactly (case-sensitive)
2. Use optional chaining: {{ $json.data?.nested?.field }}
3. Check that the upstream node actually produces the expected output

Prevention: Use pinned data to ensure consistent test data structure.

Error: ECONNREFUSED when connecting to external services

Cause: Network configuration prevents outbound connections.

Solution:

1. If behind a proxy, set HTTP_PROXY / HTTPS_PROXY
2. If using Docker, ensure the container has network access
3. Check firewall rules

Error: Python Code node ImportError

Cause: The Python task runner blocks imports by default.

Solution:

1. Add the required module to the allowlist:
   • Standard library: N8N_RUNNERS_STDLIB_ALLOW=json,math,re
   • External packages: N8N_RUNNERS_EXTERNAL_ALLOW=requests,pandas
2. Restart n8n / the task runner

Caution

The Python runner blocks dangerous builtins (eval, exec, open, __import__) and sandbox-escape patterns (access to __subclasses__, __globals__, frame objects). These restrictions are security-critical and cannot be bypassed.

7. FAQ

Q: What is the difference between test and production webhooks?

Test webhooks use the path /webhook-test/ and are only active while the workflow editor is open. Production webhooks use /webhook/ and are active whenever the workflow is active. Always use the production URL for external integrations.

Q: Can I run n8n without Docker?

Yes. Install via npm (npm install -g n8n) or build from source. Docker is recommended for production because it includes all dependencies and simplifies upgrades.

Q: How do I back up my n8n data?

For SQLite: back up the ~/.n8n/ directory (includes the database and encryption key). For PostgreSQL: use standard pg_dump. Always back up the N8N_ENCRYPTION_KEY — without it, encrypted credentials cannot be recovered.

Q: Can I use n8n with PostgreSQL instead of SQLite?

Yes. Set DB_TYPE=postgresdb and configure the PostgreSQL connection variables. PostgreSQL is required for queue mode (multi-worker) and recommended for production use.

Q: How do I upgrade n8n?

For Docker: pull the latest image and restart the container. For npm: npm update -g n8n. Database migrations run automatically on startup. Always back up before upgrading.

Q: What languages can I use in Code nodes?

JavaScript and Python. JavaScript runs in an isolated VM within the main process (or in an external JS task runner). Python runs in an external task runner with subprocess isolation and import restrictions.

Q: How do I handle large datasets in workflows?

Use the Split In Batches node to process items in chunks. For very large datasets, consider streaming approaches with the HTTP Request node and pagination.

Q: Can multiple users collaborate on workflows?

Yes. n8n supports multi-user access with projects and role-based permissions. Users can be assigned roles (owner, admin, editor, viewer) at the project level.

Q: What is queue mode?

Queue mode (EXECUTIONS_MODE=queue) separates workflow orchestration from execution. The main instance manages the UI and enqueues jobs to Redis, while worker instances execute workflows. This enables horizontal scaling. See the Admin Guide for setup details.

Q: How do I use the AI features?

Add AI nodes (AI Agent, Chat Model, Memory, Tools) to your workflow. Configure a Chat Model node with your API credentials (OpenAI, Anthropic, etc.) or use the AI Gateway for managed credentials. The AI Workflow Builder (licensed feature) can also generate workflows from natural language descriptions.

Q: Where can I find logs?

n8n logs to stdout by default. Use N8N_LOG_LEVEL to control verbosity. In Docker, use docker logs n8n. Execution logs are visible in the Executions tab in the editor.

Q: How do I set up SSO/SAML authentication?

SAML and LDAP authentication are Enterprise licensed features. Configure via N8N_SSO_* environment variables. See the Admin Guide for detailed SSO setup.