Troubleshoot n8n Provisioning
Diagnostic reference for issues encountered during template discovery, workflow import, batch provisioning, and credential setup. All tool references use ~~placeholder syntax — see CONNECTORS.md for provider fallback.
Quick Diagnostics
Run these checks first to establish instance state:
1. ~~instance_audit → check instance health, version, node inventory
2. ~~workflow_list → list existing workflows, detect conflicts
3. ~~credential_manage → list existing credentials, check types available
If the instance is unreachable, check:
- Instance URL is correct and accessible
- API key / authentication is valid
- n8n is running and healthy (check
/healthz endpoint)
Deployment Failures
| Error |
Cause |
Fix |
| Template not found (404) |
Template ID does not exist in the official library |
Verify template ID; it may have been removed or renumbered. Search by keyword instead |
| Deploy timeout |
n8n instance is slow or overloaded |
Retry with a longer timeout. Check instance resources (CPU/memory) |
| Instance unreachable |
Wrong URL, instance down, or network issue |
Verify instance URL. Check if n8n is running. Test with ~~instance_audit |
| API key invalid (401) |
Expired or incorrect API key |
Regenerate API key in n8n Settings > API. Update MCP server config |
| API key insufficient (403) |
API key lacks required permissions |
Use an Owner-level API key. Check n8n RBAC settings |
| Rate limit exceeded (429) |
Too many API calls in short period |
Wait and retry. Space out batch deployments. Check n8n rate limit config |
| Workflow already exists |
Name collision with existing workflow |
Rename the workflow before import, or append a suffix |
| Import payload too large |
Workflow JSON exceeds request size limit |
Check n8n's N8N_PAYLOAD_SIZE_MAX env var. Increase if needed |
Validation Errors
| Error |
Cause |
Fix |
| Missing node type |
Workflow uses a node not installed on the instance |
Install the missing node package. Check nodes[].type in the JSON |
| Invalid connections |
Connection references a node that doesn't exist |
Fix connection source/target node names to match actual node names |
| Deprecated node |
Workflow uses a node type removed in current n8n version |
Replace with the successor node. Check n8n migration docs |
| Schema version mismatch |
Workflow JSON format doesn't match instance version |
Update the workflow JSON format. Older workflows may need meta.instanceId |
| Invalid parameter value |
Node parameter has wrong type or invalid option |
Check node documentation for valid parameter values |
| Expression syntax error |
{{ }} expression contains invalid JavaScript |
Fix the expression. Common: missing . accessor, wrong variable name |
| Duplicate node names |
Two nodes have the same name field |
Rename one node to be unique within the workflow |
| Missing required field |
A required node parameter is not set |
Add the missing parameter. Use ~~template_get for the complete definition |
Community Node Issues
| Error |
Cause |
Fix |
| Node type not found |
Community node package not installed |
Install via n8n Settings > Community Nodes, or n8n-node-dev install {package} |
| Version mismatch |
Installed node version doesn't match workflow expectations |
Update the community node to the version the workflow expects |
| Community node deprecated |
Package removed from npm or abandoned |
Find an alternative node. Check npm for fork or replacement |
| Node crashes on execution |
Bug in community node code |
Check node's GitHub issues. Downgrade to a stable version. Report the bug |
typeVersion too high |
Workflow built with newer node version than installed |
Update the community node package to latest |
Credential Issues
| Error |
Cause |
Fix |
| Credential type not found |
Workflow references a credential type not available |
The credential type may require a community node. Install the corresponding node package |
| OAuth token expired |
OAuth2 credential needs re-authorization |
Re-authorize in n8n UI: Credentials > Edit > Reconnect |
| Wrong credential schema |
Credential fields don't match what the node expects |
Delete and recreate the credential with the correct type |
| Credential not mapped |
Workflow imported without credential assignments |
Edit each node in the workflow, select the correct credential |
| Cannot create credential via API |
n8n API doesn't support all credential types programmatically |
Create credentials manually in the n8n UI, then reference by ID |
| Credential test fails |
Credentials are correct but test endpoint is down |
Try using the credential in an actual workflow execution instead |
Batch Provisioning Issues
| Error |
Cause |
Fix |
| Partial deployment (some workflows failed) |
Individual workflow errors during batch |
Check each failed workflow's error. Fix and retry individually |
| Naming conflicts |
Multiple workflows in the batch have the same name |
Add unique suffixes before batch import |
| Webhook path collisions |
Two workflows claim the same webhook URL path |
Modify webhook paths to be unique. Use prefixes like /batch-1/... |
| Credential mapping across batch |
Shared credentials not applied to all workflows |
After batch import, map credentials to each workflow systematically |
| Tag not applied |
Batch tag failed to apply during import |
Apply tags after import using workflow update API |
| Import order violation |
Workflow depends on another that hasn't been imported yet |
Follow dependency-aware import order from BATCH_STRATEGIES.md |
Version Incompatibilities
| Error |
Cause |
Fix |
| n8n version too old for template |
Template uses features from a newer n8n version |
Upgrade n8n instance, or find an older version of the template |
typeVersion mismatch |
Node typeVersion in workflow doesn't match installed node |
Update n8n. Or manually downgrade typeVersion in the JSON (risky — test thoroughly) |
| API version mismatch |
Template uses API v2 features on a v1 instance |
Upgrade n8n or adapt the workflow to use v1 API format |
| Workflow format version |
Old workflow format missing meta or versionId fields |
Add missing fields: "meta": {"instanceId": ""}, "versionId": "" |
| Sub-workflow references |
Workflow calls sub-workflows by ID that don't exist |
Import sub-workflows first, then update the parent's sub-workflow references |
Web Scraping Failures (Community Source Discovery)
| Error |
Cause |
Fix |
| Scrape returns HTML, not JSON |
Page uses JavaScript rendering |
Try a different scrape provider (Firecrawl handles JS better). Or use raw.githubusercontent.com URLs |
| JSON parse error |
Scraped content contains extra HTML/text around the JSON |
Extract only the JSON portion. Look for {"nodes": as the start marker |
| Rate limited by GitHub |
Too many raw.githubusercontent.com requests |
Wait and retry. Or use GitHub API with authentication for higher limits |
| Workflow JSON incomplete |
Page didn't fully load, or JSON was truncated |
Retry the scrape. Try a different URL format (e.g., GitHub API instead of raw) |
| Community platform down |
Third-party site is temporarily unavailable |
Try the next platform in priority order (see COMMUNITY_PLATFORMS.md) |
Diagnostic Decision Tree
Problem reported
├── Instance unreachable?
│ → Check URL, check if n8n is running, check API key
├── Template not found?
│ → Verify ID, search by keyword, check community sources
├── Import failed?
│ ├── Validation error?
│ │ → Check node types, connections, parameters
│ ├── Permission error?
│ │ → Check API key permissions
│ └── Size error?
│ → Check payload size limits
├── Workflow imported but won't activate?
│ ├── Missing credentials?
│ │ → Map credentials in n8n UI
│ ├── Node error?
│ │ → Check for deprecated/missing nodes
│ └── Expression error?
│ → Fix expression syntax
└── Batch deployment partial failure?
→ Check individual errors, fix and retry failed workflows
When to Escalate
- Instance crashes during import — likely a memory issue. Check n8n container resources
- Persistent API 500 errors — n8n server-side issue. Check n8n logs
- Credential type completely missing — may require n8n source-level investigation
- All providers fail for web scraping — network or firewall issue on the user's side
1---2name: troubleshoot-193description: Diagnose and fix n8n provisioning and import issues. This skill should be used when the user encounters "n8n import error", "template deploy failed", "workflow validation error", "provisioning troubleshoot", "n8n provision problem", "community node missing", "credential not found", "workflow won't activate", "batch deploy failed", or needs help debugging n8n workflow import and deployment issues.4---56# Troubleshoot n8n Provisioning78Diagnostic reference for issues encountered during template discovery, workflow import, batch provisioning, and credential setup. All tool references use `~~placeholder` syntax — see CONNECTORS.md for provider fallback.910## Quick Diagnostics1112Run these checks first to establish instance state:1314```151. ~~instance_audit → check instance health, version, node inventory162. ~~workflow_list → list existing workflows, detect conflicts173. ~~credential_manage → list existing credentials, check types available18```1920If the instance is unreachable, check:21- Instance URL is correct and accessible22- API key / authentication is valid23- n8n is running and healthy (check `/healthz` endpoint)2425## Deployment Failures2627| Error | Cause | Fix |28|-------|-------|-----|29| Template not found (404) | Template ID does not exist in the official library | Verify template ID; it may have been removed or renumbered. Search by keyword instead |30| Deploy timeout | n8n instance is slow or overloaded | Retry with a longer timeout. Check instance resources (CPU/memory) |31| Instance unreachable | Wrong URL, instance down, or network issue | Verify instance URL. Check if n8n is running. Test with `~~instance_audit` |32| API key invalid (401) | Expired or incorrect API key | Regenerate API key in n8n Settings > API. Update MCP server config |33| API key insufficient (403) | API key lacks required permissions | Use an Owner-level API key. Check n8n RBAC settings |34| Rate limit exceeded (429) | Too many API calls in short period | Wait and retry. Space out batch deployments. Check n8n rate limit config |35| Workflow already exists | Name collision with existing workflow | Rename the workflow before import, or append a suffix |36| Import payload too large | Workflow JSON exceeds request size limit | Check n8n's `N8N_PAYLOAD_SIZE_MAX` env var. Increase if needed |3738## Validation Errors3940| Error | Cause | Fix |41|-------|-------|-----|42| Missing node type | Workflow uses a node not installed on the instance | Install the missing node package. Check `nodes[].type` in the JSON |43| Invalid connections | Connection references a node that doesn't exist | Fix connection `source`/`target` node names to match actual node names |44| Deprecated node | Workflow uses a node type removed in current n8n version | Replace with the successor node. Check n8n migration docs |45| Schema version mismatch | Workflow JSON format doesn't match instance version | Update the workflow JSON format. Older workflows may need `meta.instanceId` |46| Invalid parameter value | Node parameter has wrong type or invalid option | Check node documentation for valid parameter values |47| Expression syntax error | `{{ }}` expression contains invalid JavaScript | Fix the expression. Common: missing `.` accessor, wrong variable name |48| Duplicate node names | Two nodes have the same `name` field | Rename one node to be unique within the workflow |49| Missing required field | A required node parameter is not set | Add the missing parameter. Use `~~template_get` for the complete definition |5051## Community Node Issues5253| Error | Cause | Fix |54|-------|-------|-----|55| Node type not found | Community node package not installed | Install via n8n Settings > Community Nodes, or `n8n-node-dev install {package}` |56| Version mismatch | Installed node version doesn't match workflow expectations | Update the community node to the version the workflow expects |57| Community node deprecated | Package removed from npm or abandoned | Find an alternative node. Check npm for fork or replacement |58| Node crashes on execution | Bug in community node code | Check node's GitHub issues. Downgrade to a stable version. Report the bug |59| `typeVersion` too high | Workflow built with newer node version than installed | Update the community node package to latest |6061## Credential Issues6263| Error | Cause | Fix |64|-------|-------|-----|65| Credential type not found | Workflow references a credential type not available | The credential type may require a community node. Install the corresponding node package |66| OAuth token expired | OAuth2 credential needs re-authorization | Re-authorize in n8n UI: Credentials > Edit > Reconnect |67| Wrong credential schema | Credential fields don't match what the node expects | Delete and recreate the credential with the correct type |68| Credential not mapped | Workflow imported without credential assignments | Edit each node in the workflow, select the correct credential |69| Cannot create credential via API | n8n API doesn't support all credential types programmatically | Create credentials manually in the n8n UI, then reference by ID |70| Credential test fails | Credentials are correct but test endpoint is down | Try using the credential in an actual workflow execution instead |7172## Batch Provisioning Issues7374| Error | Cause | Fix |75|-------|-------|-----|76| Partial deployment (some workflows failed) | Individual workflow errors during batch | Check each failed workflow's error. Fix and retry individually |77| Naming conflicts | Multiple workflows in the batch have the same name | Add unique suffixes before batch import |78| Webhook path collisions | Two workflows claim the same webhook URL path | Modify webhook paths to be unique. Use prefixes like `/batch-1/...` |79| Credential mapping across batch | Shared credentials not applied to all workflows | After batch import, map credentials to each workflow systematically |80| Tag not applied | Batch tag failed to apply during import | Apply tags after import using workflow update API |81| Import order violation | Workflow depends on another that hasn't been imported yet | Follow dependency-aware import order from BATCH_STRATEGIES.md |8283## Version Incompatibilities8485| Error | Cause | Fix |86|-------|-------|-----|87| n8n version too old for template | Template uses features from a newer n8n version | Upgrade n8n instance, or find an older version of the template |88| `typeVersion` mismatch | Node `typeVersion` in workflow doesn't match installed node | Update n8n. Or manually downgrade `typeVersion` in the JSON (risky — test thoroughly) |89| API version mismatch | Template uses API v2 features on a v1 instance | Upgrade n8n or adapt the workflow to use v1 API format |90| Workflow format version | Old workflow format missing `meta` or `versionId` fields | Add missing fields: `"meta": {"instanceId": ""}`, `"versionId": ""` |91| Sub-workflow references | Workflow calls sub-workflows by ID that don't exist | Import sub-workflows first, then update the parent's sub-workflow references |9293## Web Scraping Failures (Community Source Discovery)9495| Error | Cause | Fix |96|-------|-------|-----|97| Scrape returns HTML, not JSON | Page uses JavaScript rendering | Try a different scrape provider (Firecrawl handles JS better). Or use raw.githubusercontent.com URLs |98| JSON parse error | Scraped content contains extra HTML/text around the JSON | Extract only the JSON portion. Look for `{"nodes":` as the start marker |99| Rate limited by GitHub | Too many raw.githubusercontent.com requests | Wait and retry. Or use GitHub API with authentication for higher limits |100| Workflow JSON incomplete | Page didn't fully load, or JSON was truncated | Retry the scrape. Try a different URL format (e.g., GitHub API instead of raw) |101| Community platform down | Third-party site is temporarily unavailable | Try the next platform in priority order (see COMMUNITY_PLATFORMS.md) |102103## Diagnostic Decision Tree104105```106Problem reported107├── Instance unreachable?108│ → Check URL, check if n8n is running, check API key109├── Template not found?110│ → Verify ID, search by keyword, check community sources111├── Import failed?112│ ├── Validation error?113│ │ → Check node types, connections, parameters114│ ├── Permission error?115│ │ → Check API key permissions116│ └── Size error?117│ → Check payload size limits118├── Workflow imported but won't activate?119│ ├── Missing credentials?120│ │ → Map credentials in n8n UI121│ ├── Node error?122│ │ → Check for deprecated/missing nodes123│ └── Expression error?124│ → Fix expression syntax125└── Batch deployment partial failure?126 → Check individual errors, fix and retry failed workflows127```128129## When to Escalate130131- **Instance crashes during import** — likely a memory issue. Check n8n container resources132- **Persistent API 500 errors** — n8n server-side issue. Check n8n logs133- **Credential type completely missing** — may require n8n source-level investigation134- **All providers fail for web scraping** — network or firewall issue on the user's side
agents-store