InstaGist Troubleshooting Guide

Quick solutions to common issues when setting up and running InstaGist.

Pre-Flight Checklist

Before testing your workflow, verify:

n8n is running and accessible
Webhook node is created and workflow is Active
yt-dlp is installed: which yt-dlp (should return a path)
FFmpeg is installed: which ffmpeg (should return a path)
OpenAI credentials are configured in n8n
/tmp directory is writable: touch /tmp/test && rm /tmp/test

Run the dependency checker:

./scripts/check-dependencies.sh

Common Errors

1. Webhook Returns Nothing

Symptom: curl hangs or returns empty response

Causes:

Workflow is not Active
Wrong webhook URL
n8n not running

Solution:

# Check if n8n is running
curl http://localhost:5678

# Check workflow is active in n8n UI
# Verify webhook URL matches your test

# Test the webhook directly in n8n using the "Test URL" button

2. "yt-dlp: command not found"

Symptom: Execute Command node fails with command not found

Causes:

yt-dlp not installed on the server where n8n runs
yt-dlp not in PATH

Solution for Render.com:

# Build and push custom Docker image with yt-dlp
./scripts/build-and-push.sh your-dockerhub-username

# Deploy to Render.com using your custom image
# See DEPLOY_TO_RENDER.md

Solution for local/self-hosted:

# macOS
brew install yt-dlp

# Linux
pip3 install yt-dlp

# Verify
yt-dlp --version

Quick fix for testing: Use the full path to yt-dlp if it's installed but not in PATH:

# Find yt-dlp
which yt-dlp
# or
find / -name yt-dlp 2>/dev/null

# Use full path in Execute Command node
/usr/local/bin/yt-dlp -f "best[ext=mp4]/best" ...

3. "ffmpeg: command not found"

Symptom: Audio extraction fails

Solution:

# macOS
brew install ffmpeg

# Linux
sudo apt update && sudo apt install ffmpeg

# Verify
ffmpeg -version

For Render.com, use the custom Docker image (includes FFmpeg).

4. Instagram Download Fails

Symptom: yt-dlp returns error like "Video unavailable" or "Unable to download"

Possible Causes:

Private account
Video deleted
Geographic restrictions
Instagram blocking the request
Rate limiting

Solutions:

Try a different video first to verify it's not your setup:

# Test with a known-working public reel
curl -X POST http://localhost:5678/webhook/instagram-gist \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.instagram.com/reel/DOgC-ZjiEF3/"}'

Add user-agent to yt-dlp command:

yt-dlp --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
  -f "best[ext=mp4]/best" \
  --no-playlist \
  -o "/tmp/insta-gist-{{ $json.body.url.split('/')[4] }}.mp4" \
  "{{ $json.body.url }}"

Update yt-dlp (Instagram changes frequently):

pip3 install --upgrade yt-dlp

Test yt-dlp directly from command line:

# SSH into your server
yt-dlp -f "best[ext=mp4]/best" "https://www.instagram.com/reel/DOgC-ZjiEF3/"

5. OpenAI Whisper API Error

Symptom: 400 or 413 error from Whisper API

Causes:

Audio file too large (>25MB)
Invalid audio format
Missing API key
Wrong file path

Solutions:

Check file size:

# Add a debug Execute Command node
ls -lh /tmp/insta-gist-*.mp3

Verify audio was created:

# Add after FFmpeg node
ls -la /tmp/insta-gist-*
file /tmp/insta-gist-*.mp3

If file is too large, compress more aggressively:

ffmpeg -i {{ $json.videoPath }} \
  -vn -acodec libmp3lame \
  -ac 1 -ar 16000 -ab 64k \
  {{ $json.audioPath }} -y

Verify API key:

Check OpenAI credentials in n8n: Credentials → OpenAI API

Test key manually:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

6. GPT-4 API Error

Symptom: 401, 429, or 500 error from OpenAI

Causes:

Invalid API key
Insufficient credits
Rate limit exceeded
Model not available

Solutions:

Check API key and credits:

Visit OpenAI Usage Dashboard
Verify you have available credits
Check API key is active

Use GPT-4o-mini instead (cheaper, faster):

{
  "model": "gpt-4o-mini",
  "messages": [ ... ]
}

Handle rate limits: Add retry logic or wait 60 seconds

7. Workflow Times Out

Symptom: Execution never completes or returns timeout error

Causes:

Long video (>5 minutes)
Slow network/API
Default timeout too short

Solutions:

Increase execution timeout in n8n:

Settings → Workflows
Execution Timeout: increase to 600 (10 minutes)

For Render.com, add environment variable:

EXECUTIONS_TIMEOUT=600
EXECUTIONS_TIMEOUT_MAX=900

Add timeout to individual nodes:

Click node → Settings → Timeout
Set to 300 seconds (5 minutes)

8. Files Not Cleaned Up

Symptom: /tmp fills up with video files

Causes:

Cleanup node not executing
Workflow error before cleanup
Wrong file paths

Solutions:

Ensure cleanup always runs: Move cleanup to error handler too

Manual cleanup:

# SSH into server
rm -f /tmp/insta-gist-*

Automatic cleanup with cron (Linux):

# Add to crontab
0 * * * * find /tmp -name "insta-gist-*" -mtime +1 -delete

9. Webhook Returns Error but Workflow Seems Fine

Symptom: curl shows error but n8n shows success

Causes:

Not using "Respond to Webhook" node
Response node not connected
Multiple response nodes conflicting

Solution:

Ensure workflow uses Respond to Webhook node
Verify it's connected to the end of the workflow
Check workflow has only ONE response per path (success/error)

10. URL with Query Parameters Fails

Symptom: Instagram URLs like https://instagram.com/reel/ABC/?igsh=xyz fail to parse

Cause: URL splitting assumes clean URLs

Solution: Clean URL before processing:

// In Set node for videoId
{{ $json.body.url.split('?')[0].split('/')[4] }}

Or use regex to extract video ID:

{{ $json.body.url.match(/\/reel\/([^\/\?]+)/)[1] }}

Debugging Tips

1. Test Nodes Individually

Click "Execute Node" button on each node
Verify output before moving to next node
Check the "Output" tab for data

2. Enable Debug Logging

Add Execute Command nodes to log progress:

echo "Step completed: Download" >> /tmp/workflow-debug.log

3. Check n8n Execution Logs

Go to "Executions" tab in n8n
Click on failed execution
Expand each node to see error details

4. Test Components Separately

Test yt-dlp directly:

yt-dlp -v "https://www.instagram.com/reel/DOgC-ZjiEF3/"

Test FFmpeg:

ffmpeg -i /tmp/test-video.mp4 -vn -acodec libmp3lame /tmp/test-audio.mp3

Test OpenAI API:

curl https://api.openai.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F file="@/tmp/test-audio.mp3" \
  -F model="whisper-1"

5. Check Server Resources

# Check disk space
df -h /tmp

# Check memory
free -h

# Check n8n logs
docker logs n8n  # if running in Docker

Performance Issues

Slow Processing

Expected times (for 60-second video):

Download: 5-15 seconds
Audio extraction: 2-5 seconds
Transcription: 15-30 seconds
Summary: 3-10 seconds
Total: 25-60 seconds

If slower:

Check internet connection speed
Check server CPU/memory usage
OpenAI API may be experiencing slowdowns

High Costs

Cost per video (~60 seconds):

Whisper: $0.006/minute = ~$0.006
GPT-4o-mini: ~$0.002
Total: ~$0.01 per video

If costs are higher:

You might be using gpt-4 instead of gpt-4o-mini (100x more expensive)
Check your OpenAI usage dashboard
Implement caching to avoid reprocessing

Getting Help

If you're still stuck:

Check n8n community: community.n8n.io
n8n documentation: docs.n8n.io
Test with minimal workflow: Start with just webhook + response
Check logs: n8n execution logs have detailed error messages

Quick Test Script

Use this to verify everything is working:

#!/bin/bash

echo "Testing InstaGist setup..."

# Test 1: n8n running
echo "1. Testing n8n..."
curl -s http://localhost:5678 > /dev/null && echo "✓ n8n is running" || echo "✗ n8n not accessible"

# Test 2: yt-dlp installed
echo "2. Testing yt-dlp..."
which yt-dlp > /dev/null && echo "✓ yt-dlp found" || echo "✗ yt-dlp not found"

# Test 3: FFmpeg installed
echo "3. Testing ffmpeg..."
which ffmpeg > /dev/null && echo "✓ ffmpeg found" || echo "✗ ffmpeg not found"

# Test 4: Temp directory writable
echo "4. Testing /tmp..."
touch /tmp/test-file 2>/dev/null && rm /tmp/test-file && echo "✓ /tmp writable" || echo "✗ /tmp not writable"

# Test 5: OpenAI API key (if set)
if [ -n "$OPENAI_API_KEY" ]; then
    echo "5. Testing OpenAI API..."
    curl -s https://api.openai.com/v1/models \
        -H "Authorization: Bearer $OPENAI_API_KEY" | grep -q "gpt-4" \
        && echo "✓ OpenAI API key valid" || echo "✗ OpenAI API key invalid"
else
    echo "5. Skipping OpenAI test (no API key in env)"
fi

echo "Done!"

Save as test-setup.sh and run: chmod +x test-setup.sh && ./test-setup.sh

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

InstaGist Troubleshooting Guide

Pre-Flight Checklist

Common Errors

1. Webhook Returns Nothing

2. "yt-dlp: command not found"

3. "ffmpeg: command not found"

4. Instagram Download Fails

5. OpenAI Whisper API Error

6. GPT-4 API Error

7. Workflow Times Out

8. Files Not Cleaned Up

9. Webhook Returns Error but Workflow Seems Fine

10. URL with Query Parameters Fails

Debugging Tips

1. Test Nodes Individually

2. Enable Debug Logging

3. Check n8n Execution Logs

4. Test Components Separately

5. Check Server Resources

Performance Issues

Slow Processing

High Costs

Getting Help

Quick Test Script