Troubleshooting

Common issues and solutions for the DeepTagger n8n node.

Installation Issues

Node doesn't appear after installation

Symptoms: Can't find DeepTagger in node list

Solutions:

1. Restart n8n completely

   # Self-hosted
   pm2 restart n8n
   # Or kill the process and start again
   
   # Docker
   docker restart n8n-container
   

2. Verify installation

   npm list n8n-nodes-deeptagger
   

   Should show: n8n-nodes-deeptagger@x.x.x

3. Check n8n logs

   # Standard installation
   tail -f ~/.n8n/n8n.log
   
   # Docker
   docker logs -f n8n-container
   

4. Clear browser cache

5. Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)

npm install fails

Error: npm ERR! code EACCES

Solution:

# Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install n8n-nodes-deeptagger

Error: npm ERR! network

Solution:

# Clear cache and retry
npm cache clean --force
npm install n8n-nodes-deeptagger

Authentication Issues

Error: "No API key found in request"

Cause: Credential not configured or not selected

Solutions:

1. Create DeepTagger API credential:
2. Go to Credentials → New Credential
3. Search "DeepTagger API"

4. Enter API Key and Base URL

5. Select credential in node:

6. Click on DeepTagger node

7. Choose credential from dropdown

8. Verify API key is not empty in credential settings

Error: "Unauthorized" or "401"

Cause: Invalid or expired API key

Solutions:

1. Verify API key in DeepTagger dashboard
2. Login to deeptagger.com
3. Go to Settings → API Keys

4. Check key is active

5. Regenerate API key:

6. Create new key in dashboard
7. Update credential in n8n

8. Test again

9. Check for extra spaces:

10. API key should have no leading/trailing spaces
11. Copy directly from dashboard

Error: "Invalid base URL" or "Network Error"

Cause: Incorrect base URL or connectivity issue

Solutions:

1. Verify base URL is exactly:

   https://deeptagger.com/api/v1
   

   (No trailing slash!)

2. Check for typos:

3. http vs https

4. /api/v1 vs /api/v2

5. Test connectivity:

   curl https://deeptagger.com/api/v1/health
   

6. Check firewall (self-hosted only):

7. Ensure n8n can reach deeptagger.com
8. Whitelist in corporate firewall if needed

Execution Issues

Error: "Project not found" or "404"

Cause: Incorrect Project ID

Solutions:

1. Verify Project ID format:
2. Must start with fo_

3. Example: fo_1759714105892

4. Get correct Project ID:

5. Go to deeptagger.com/das/fos
6. Open your project

7. Copy ID from URL bar

8. Check project exists:

9. Log in to DeepTagger dashboard
10. Verify project is not deleted

No data extracted (empty result {})

Cause: Untrained project or wrong document type

Solutions:

1. Verify project is trained:
2. Go to DeepTagger dashboard
3. Open project

4. Check it has 3+ training examples

5. Test in dashboard first:

6. Upload same document in DeepTagger UI
7. Verify it extracts correctly

8. If it doesn't work in UI, train more examples

9. Check document quality:

10. Is the PDF readable?
11. Is text selectable (not scanned image)?

12. Try a different document

13. Verify document type matches:

14. Invoice project should process invoices
15. Don't send receipts to invoice project

Error: "Binary data not found"

Cause: Previous node doesn't output binary data

Solutions:

1. Check previous node outputs binary:
2. HTTP Request (binary mode)
3. Webhook (file upload)
4. Google Drive / Dropbox

5. Email (with download attachments)

6. Verify Binary Property name:

7. Check previous node's output
8. Common values: data, attachment0, file

9. Set DeepTagger Binary Property to match

10. Use Move Binary Data node:

11. Add between nodes
12. Move binary from custom property to data

Text input doesn't work

Cause: Wrong Input Type or missing text

Solutions:

1. Set Input Type to "Text"

2. Provide text content:

3. Can be hardcoded for testing

4. Or dynamic: {{$json["body"]}}

5. Check text is not empty:

6. Add Code node before to debug
7. Log: console.log($json)

Performance Issues

Execution timeout

Cause: Large files or slow network

Solutions:

1. Increase timeout in n8n settings:
2. Settings → General → Execution Timeout
3. Default: 120 seconds

4. Try: 300 seconds (5 min)

5. Optimize file size:

6. Compress PDFs before processing

7. Split large documents

8. Check network:

9. Test API speed outside n8n
10. Contact support if consistently slow

Rate limit errors

Cause: Too many requests

Solutions:

1. Add delays in batch workflows:
2. Wait node between iterations

3. 1-2 second delay recommended

4. Reduce concurrency:

5. Process files sequentially, not in parallel

6. Use Loop node instead of multiple branches

7. Check your plan limits:

8. Login to DeepTagger dashboard
9. View API usage and limits
10. Upgrade plan if needed

Data Quality Issues

Extracted data is inaccurate

Cause: Needs more training or document variation

Solutions:

1. Add more training examples:
2. Minimum: 3 examples
3. Recommended: 5-10 examples

4. Include variety of document layouts

5. Review annotations:

6. Check training examples in dashboard
7. Ensure selections are accurate

8. Re-annotate if needed

9. Check document quality:

10. Low-resolution images reduce accuracy
11. Scanned documents may need OCR cleanup

Missing fields in output

Cause: Field not present or not trained

Solutions:

1. Check if field exists in document:
2. Some invoices may not have all fields

3. Handle missing data in workflow

4. Verify field is in project schema:

5. Dashboard → Project → Schema

6. Add missing fields if needed

7. Train with examples containing that field:

8. Annotate at least 3 examples with the field

Wrong data type (string instead of number)

Cause: DeepTagger returns all data as strings

Solutions:

1. Convert in n8n expression:

   // String to number
   {{parseFloat($json["total"].replace("$", "").replace(",", ""))}}
   
   // String to date
   {{new Date($json["date"])}}
   

2. Use Code node for complex transformations

Workflow Issues

Duplicate entries in database

Cause: Workflow running multiple times

Solutions:

1. Implement duplicate check:
2. Query database before insert

3. Check unique field (invoice number)

4. Use idempotency keys:

5. Add unique ID to each execution

6. Skip if ID already processed

7. Archive processed items:

8. Move processed emails to folder
9. Mark files as processed

Workflow fails on some documents

Cause: Inconsistent document format or extraction failures

Solutions:

1. Enable "Continue on Fail":
2. Node settings → Continue on Fail

3. Workflow continues even if node fails

4. Add error handling:

5. IF node after DeepTagger
6. Check: {{$json["error"] === undefined}}

7. Success branch vs Error branch

8. Log errors:

9. Send failed items to error database
10. Review and retrain with failed examples

Docker/Kubernetes Issues

Node not available in Docker

Cause: Package not installed in container

Solutions:

1. Install at runtime:

   docker exec -it n8n-container /bin/bash
   npm install n8n-nodes-deeptagger
   exit
   docker restart n8n-container
   

2. Use custom Dockerfile:

   FROM n8nio/n8n:latest
   RUN cd /usr/local/lib/node_modules/n8n && npm install n8n-nodes-deeptagger
   

3. Persist installation:

4. Mount /home/node/.n8n volume
5. Installation persists across restarts

Kubernetes pod restarts lose node

Cause: No persistent volume

Solutions:

1. Use PersistentVolumeClaim:

   volumeMounts:
     - name: n8n-data
       mountPath: /home/node/.n8n
   volumes:
     - name: n8n-data
       persistentVolumeClaim:
         claimName: n8n-pvc
   

2. Or use init container (see Installation)

Getting Additional Help

If these solutions don't resolve your issue:

1. Check Documentation

• Installation Guide
• Authentication Setup
• Operations Reference
• API Documentation

2. Search GitHub Issues

github.com/deeptaggerhq/n8n-nodes-deeptagger/issues

• Search existing issues
• Check if your problem is already reported
• See solutions from community

3. Open a New Issue

When creating an issue, include:

• n8n version: n8n --version or from Settings
• Node version: node --version
• DeepTagger node version: Check in package.json or npm list
• Installation method: npm, Docker, Kubernetes
• Error message: Full error with stack trace
• Steps to reproduce: Workflow JSON if possible (remove sensitive data!)
• What you've tried: List solutions you've attempted

4. Contact Support

For n8n node issues: - GitHub: github.com/deeptaggerhq/n8n-nodes-deeptagger/issues

For DeepTagger API/platform issues: - Email: support@deeptagger.com - Dashboard: Help widget (bottom-right)

For n8n platform issues: - Forum: community.n8n.io - Docs: docs.n8n.io

5. Community Resources

• n8n Community Forum
• DeepTagger Discord (coming soon)
• Stack Overflow (tag: n8n + deeptagger)

Debug Mode

Enable debug logging in n8n for detailed error information:

# Self-hosted
export N8N_LOG_LEVEL=debug
n8n start

# Docker
docker run -e N8N_LOG_LEVEL=debug n8nio/n8n

Check logs for detailed API requests/responses.

Reporting Bugs

Found a bug? Help us fix it!

1. Verify it's a bug (not expected behavior)
2. Check it's reproducible (happens every time)
3. Create minimal test case (simplest workflow that shows the bug)
4. Open issue on GitHub with:
5. Title: Brief description
6. Environment: n8n version, OS, installation method
7. Steps to reproduce
8. Expected behavior
9. Actual behavior
10. Workflow JSON (if applicable)
11. Screenshots (if helpful)

Thank you for helping improve DeepTagger!