• Automated Product …
• Documentation
• Troubleshooting Common …

Troubleshooting Common Issues

If you’re running into issues using FreshShots — whether with API calls, CDN image display, or screenshot workflows — this guide will help you diagnose and resolve common problems.

---

📡 API Troubleshooting

❌ 401 Unauthorized

Symptoms:

• API call fails with a 401 error
• Response message: Invalid or missing API key

Fix:

• Make sure you’re including the correct API key in the x-api-key header.
• Check for typos or accidental whitespace.
• If you’re using secrets in CI/CD, confirm the key is injected properly.

---

❌ 404 Not Found

Symptoms:

• API call fails with a 404 error
• Response: "Workflow not found" or "Screenshot not found"

Fix:

• Double-check your workflow_id, user_id, or screenshot_id
• Ensure the workflow actually exists and hasn’t been deleted or renamed.

---

❌ 429 Too Many Requests

Symptoms:

• You’re hitting rate limits.

Fix:

• Avoid spamming the API with repeated calls.
• Use retries with exponential backoff.
• Contact support if you need a higher rate limit.

---

📸 Screenshot Not Capturing

🕒 Job stuck in pending or running forever

Fix:

• The URL being captured might be slow or blocking headless browsers.
• Ensure the site is accessible from a server (not behind VPN, auth, or firewall).
• Try opening the target URL in Playwright headless mode locally to reproduce.

---

📷 Blank / Empty Screenshot

Fix:

• Use waitForSelector or waitUntil: 'networkidle' in your workflow step to wait for content.
• Make sure your app supports headless browsers and doesn’t block automation.
• Check if elements require scrolling or manual interaction to appear.

---

❗ Element not found with data-freshshots-id

Fix:

• Double-check the selector exists in the HTML.
• Ensure dynamic content has time to render.
• You may need to set an explicit wait time or selector.

---

🌐 CDN Issues

🖼️ Image not loading in Docs

Fix:

• Confirm the CDN URL is correct (case-sensitive!)
• Try pasting the image link in a browser to test it directly.
• Some tools (e.g. Notion, Google Docs) block hotlinks in rare cases — try uploading manually or re-embedding.

---

🔒 403 Forbidden

Fix:

• The screenshot may have been deleted or restricted.
• You might be trying to access a private image without proper access.
• Ensure the CDN URL is correct and not expired (for time-limited links, if enabled).

---

🧪 Testing Your Setup

If things aren’t working, try:

• Manually triggering your workflow via API or dashboard
• Checking your server logs or webhook responses
• Using tools like Postman or curl to replicate calls
• Inspecting the headless browser output (coming soon: debug screenshots!)

---

🆘 Still Stuck?

Contact us anytime at [email protected]. Include:

• Your workflow ID
• The error message or screenshot
• What docs tool or CI/CD you’re using (if relevant)

We’re happy to debug with you.