Skip to content

Shimmy Vision Troubleshooting

Jump to bottom
Michael A. Kuykendall edited this page Dec 16, 2025 · 2 revisions

Shimmy Vision Troubleshooting

Common issues and solutions for Shimmy Vision.

Quick Diagnostics

# Check server is running
curl -s http://127.0.0.1:11435/health

# Check with verbose output
curl -v http://127.0.0.1:11435/api/vision \
  -H "Content-Type: application/json" \
  -d '{"license": "YOUR-KEY", "url": "https://example.com", "mode": "brief"}'

HTTP Error Codes

400 Bad Request

Meaning: Invalid request format or missing required fields.

Common Causes:

  • Neither url nor image_base64 provided
  • Invalid JSON syntax
  • Invalid mode value

Solution:

// ✅ Correct - provide url OR image_base64
{
  "license": "YOUR-KEY",
  "url": "https://example.com",
  "mode": "brief"
}

// ❌ Wrong - missing both url and image_base64
{
  "license": "YOUR-KEY",
  "mode": "brief"
}

402 Payment Required

Meaning: No license key provided.

Common Causes:

  • Missing license field in request
  • Empty license value

Solution:

// ✅ Correct
{
  "license": "YOUR-LICENSE-KEY",
  "url": "https://example.com"
}

// ❌ Wrong - missing license
{
{"url": "https://example.com"}
}

Get a License: Purchase a license to get started.

403 Forbidden

Meaning: License validation failed.

Common Causes:

  • Invalid license key
  • Expired license
  • Suspended license
  • License missing VISION_ANALYSIS entitlement

Diagnosis:

# Check your license status directly
curl -X POST "https://api.keygen.sh/v1/accounts/YOUR_ACCOUNT/licenses/actions/validate-key" \
  -H "Content-Type: application/json" \
  -d '{"meta": {"key": "YOUR-KEY"}}'

Solutions:

Error Message Solution
"License expired" Renew your license
"License suspended" Contact support
"Invalid license" Check for typos in license key
"Missing entitlement" Upgrade to Vision-enabled plan

422 Unprocessable Entity

Meaning: Request understood but cannot be processed.

Common Causes:

  • Image too large
  • Unsupported image format
  • Corrupted base64 data

Solution:

# Check image size
identify myimage.png  # ImageMagick

# Resize if needed
convert myimage.png -resize 1920x1080\> myimage_resized.png

# Re-encode
base64 -w0 myimage_resized.png > myimage.b64

Supported Formats: PNG, JPEG, WebP, GIF (first frame)

Max Dimensions: 4096x4096 pixels

502 Bad Gateway

Meaning: Backend processing error.

Common Causes:

  • Vision model failed to load
  • Out of memory (OOM)
  • GPU driver issues

Solutions:

  1. Check server logs:
# If running manually
shimmy serve --bind 127.0.0.1:11435 2>&1 | tee server.log
  1. Restart server:
# Kill existing process
pkill -f "shimmy serve"

# Restart
shimmy serve --bind 127.0.0.1:11435
  1. Check GPU memory (if using CUDA):
nvidia-smi

504 Gateway Timeout

Meaning: Request took too long.

Common Causes:

  • Very large image
  • Complex page with many elements
  • Slow network (for URL screenshots)
  • Model inference timeout

Solutions:

  1. Reduce image size:
# Resize before sending
convert large_image.png -resize 1920x1080\> smaller.png
  1. Use simpler mode:
// Use 'brief' instead of 'full'
{
  "license": "YOUR-KEY",
  "url": "https://example.com",
  "mode": "brief"  // faster than 'full'
}
  1. For batch processing, reduce concurrency:
{
  "license": "YOUR-KEY",
  "items": [...],
  "concurrency": 1  // process one at a time
}

Screenshot Issues

Chrome Not Found

Error: Failed to capture screenshot: Chrome not found

Solutions:

  1. Install Chrome:

    • Windows: Download from google.com/chrome
    • macOS: brew install --cask google-chrome
    • Linux: apt install google-chrome-stable

  2. Set Chrome path manually:

export CHROME_PATH=/path/to/chrome
shimmy serve --bind 127.0.0.1:11435

Screenshot Blank or Incomplete

Cause: Page didn't fully load before screenshot.

Solution: The server waits for page load automatically. If issues persist:

  1. Try a different viewport size:
{
  "license": "YOUR-KEY",
  "url": "https://slow-site.com",
  "mode": "web",
  "screenshot": true,
  "viewport_width": 1280,
  "viewport_height": 720
}
  1. For JavaScript-heavy sites, page may need more time - retry the request.

Performance Issues

Slow First Request

Expected behavior: The first request loads the vision model into memory (5-15 seconds).

Subsequent requests are much faster (typically <2 seconds).

High Memory Usage

The vision model requires approximately:

  • CPU mode: ~4GB RAM
  • GPU mode: ~4GB VRAM + ~2GB RAM

Solutions:

  1. Close other applications
  2. Use GPU mode if available (faster and offloads from RAM)
  3. Process images sequentially rather than in parallel

GPU Not Being Used

Check GPU detection:

# Server should log GPU info at startup
shimmy serve --bind 127.0.0.1:11435

# Manual check
nvidia-smi

Ensure CUDA features enabled:

cargo install shimmy --features llama,vision,llama-cuda

Network Issues

Connection Refused

curl: (7) Failed to connect to 127.0.0.1 port 11435: Connection refused

Solutions:

  1. Verify server is running:
ps aux | grep shimmy
  1. Check port isn't in use:
netstat -an | grep 11435
  1. Start server:
shimmy serve --bind 127.0.0.1:11435

SSL/TLS Errors (for URL screenshots)

Error: Screenshot fails for HTTPS sites.

Solution: Chrome handles SSL internally. If issues persist:

  1. Update Chrome to latest version
  2. Check system certificates are up to date

Batch Processing Issues

SSE Stream Disconnects

Cause: Network timeout or client disconnect.

Solutions:

  1. Use a client that supports SSE properly:
import requests

# Use stream=True for SSE
response = requests.post(url, json=data, stream=True)
for line in response.iter_lines():
    if line.startswith(b"data: "):
        # Process event
        pass
  1. Reduce batch size for unstable networks.

Items Not Processing

Cause: Duplicate id values in batch items.

Solution: Ensure each item has a unique ID:

{
  "items": [
    {"id": "unique-1", "url": "..."},
    {"id": "unique-2", "url": "..."}  // ✅ Different ID
  ]
}

// ❌ Wrong - duplicate IDs
{
  "items": [
    {"id": "same", "url": "..."},
    {"id": "same", "url": "..."}  // Will cause issues
  ]
}

Getting Help

If your issue isn't covered here:

  1. Check the logs: Run server with verbose output
  2. Search issues: GitHub Issues
  3. Open a new issue: Include:
    • Error message
    • Request payload (redact license key)
    • Server version (shimmy --version)
    • OS and architecture
  4. Contact support: targetedwebresults.com/#contact

See Also

Clone this wiki locally