This guide helps you resolve common issues when using n8n-deploy.

🚨 Common Problems and Solutions

1. API Key Issues

Symptom: Unable to connect to n8n server

Solutions:

# Test API key
n8n-deploy apikey test my_server

# Verify server URL
n8n-deploy --server-url http://n8n.example.com:5678 wf list-server

# Use verbose flag for more details
n8n-deploy --verbose apikey test my_server

2. Database Initialization Problems

Symptom: Database not found or cannot be created

Use the --import flag to accept an existing database without prompting.

Solutions:

# Reinitialize database with import flag
n8n-deploy db init --import

# Check database status
n8n-deploy db status

# Specify custom app directory
n8n-deploy --data-dir /custom/path db init

3. Workflow Pull/Push Failures

Symptom: Cannot pull or push workflows

Warning: SSL verification issues? Use --skip-ssl-verify flag for self-signed certificates, but be aware of security implications.

Read-only fields: n8n-deploy automatically strips read-only fields (id, triggerCount, updatedAt, createdAt, versionId, staticData, tags, meta) before push operations. If you encounter 400 errors with manually edited workflow files, ensure you’re using the latest version.

Solutions:

# Check server connectivity
n8n-deploy --server-url http://n8n.example.com:5678 wf list-server

# Skip SSL verification (for self-signed certs)
n8n-deploy --server-url https://n8n.example.com:5678 --skip-ssl-verify wf list-server

# Verify workflow name exactly
n8n-deploy wf pull "Exact Workflow Name"

4. Configuration Verification

Symptom: Unexpected configuration behavior

Solutions:

# Show current configuration
n8n-deploy env

# Show configuration in JSON
n8n-deploy env --json

# Check environment variables
echo $N8N_SERVER_URL
echo $N8N_DEPLOY_FLOWS_DIR

5. Folder Sync Issues

Symptom: Cannot sync folders or authentication fails

Solutions:

# Authenticate with n8n server first
n8n-deploy folder auth myserver --email user@example.com

# Or use browser cookie
n8n-deploy folder auth myserver --cookie "n8n-auth=..."

# List folders to verify connection
n8n-deploy folder list --remote myserver

# Use dry-run to preview changes
n8n-deploy folder sync --dry-run

Folder sync uses n8n’s internal API (cookie-based auth), which is different from the public API (API key auth). You must authenticate separately for folder operations.

Debugging Techniques

Verbose Mode

n8n-deploy supports two levels of verbosity for debugging:

# Basic verbose - shows HTTP requests
n8n-deploy -v wf push workflow-name --remote production

# Extended verbose - shows request/response details
n8n-deploy -vv wf push workflow-name --remote production

# Verbose flag can be used at root or subcommand level
n8n-deploy -v wf push workflow-name    # Root level
n8n-deploy wf -v push workflow-name    # Subcommand level (same effect)
n8n-deploy db -vv status               # Works on any subcommand group

Environment Debugging

# Set testing environment variable
N8N_DEPLOY_TESTING=1 n8n-deploy <command>

📋 System Requirements Check

Verify Python Version

python --version  # Should be 3.9+

Check Dependencies

pip list | grep -E "n8n-deploy|click|rich|pydantic|requests"

🆘 Getting Help

CLI Help

n8n-deploy --help
n8n-deploy wf --help
n8n-deploy apikey --help

Online Resources

Tip: Always use the latest version of n8n-deploy for bug fixes and new features.

Use environment variables for consistent configuration across terminal sessions. Run n8n-deploy env to verify your settings.

🚧 Known Limitations

  • Limited to n8n workflow management
  • Requires API key for server operations
  • No automatic workflow synchronization
  • Supports SQLite backend only

📖 Related Guides

🐛 Reporting Issues

  1. Check existing GitHub issues
  2. Collect relevant logs and configuration details
  3. Create a new issue with:
    • Detailed description
    • Steps to reproduce
    • Python and n8n-deploy versions
    • System information