Troubleshooting

Common Issues

"My images are broken / blank"

Cause: The 7-day retention policy.

• Solution: Unscheduled generated pins are cleaned up after 7 days. Download your pins (ZIP or CSV) within 7 days of generation, or schedule them to Pinterest. Pending scheduled pins are retained until publish, failure, or cancellation.

"Sitemap not found"

Cause: Your website might not have a public sitemap.xml, or it's blocked by a firewall (e.g., Cloudflare).

• Solution:
  1. Try entering the direct URL: https://yoursite.com/sitemap_index.xml.
  2. Check if your robots.txt blocks bots.
  3. PinBuilds includes a Cloudflare bypass — if your sitemap is behind Cloudflare, it will attempt a headless browser fallback automatically.

"Products are not loading"

Cause: The selected profile may be the wrong type or the store feed may not be public.

• Solution:
  1. Use a Shopify Store profile for Shopify storefronts and an Etsy Shop profile for Etsy shops.
  2. For Etsy, save the shop URL in Settings, e.g. https://www.etsy.com/shop/ShopName, not an individual listing URL.
  3. Confirm the store or shop is public and has active products.
  4. If an Etsy shop only shows a small recent slice of products, contact support so the Etsy catalog connector can be checked. See Etsy Product Workflows for details on Etsy imports.

"Generation Failed"

Cause: Temporary AI service issues.

• Solution: Wait a moment and try again. PinBuilds uses automatic failover between image providers, so most issues resolve quickly. If the problem persists, contact support@pinbuilds.com.

"Pinterest account needs to be reconnected"

Cause: Your Pinterest OAuth token has expired or been revoked.

• Solution: Go to Settings, find the affected profile, and click "Connect Pinterest" to re-authorize. Your scheduled pins are preserved and will resume publishing once reconnected.

Scheduled pin shows "Failed"

Cause: Various issues can prevent a pin from publishing — expired tokens, Pinterest API errors, or invalid image URLs.

• Solution: Hover over the failed pin in the Manage Pins tab to see the error message. You can click "Retry" to re-queue it. If the error mentions authentication, reconnect your Pinterest account in Settings first.

WordPress plugin: posts not generating pins

Cause: The API key may be disconnected, or the post URL may be filtered as a generic page.

• Solution:
  1. Check that your API key is connected in Settings > PinBuilds in WordPress.
  2. Ensure the matching PinBuilds profile is a Website / Blog profile for your WordPress domain.
  3. Ensure the post URL is a real article — generic pages (about, contact, privacy, category archives) are automatically skipped.
  4. Check the backlog status — if your monthly generation limit is exhausted, processing pauses automatically.

Frequently Asked Questions

Can I use my own prompts?

Currently, PinBuilds uses optimized internal prompts tuned for Pinterest engagement. We update these regularly based on performance data. You can control the visual style by selecting different image styles per profile.

Which profile type should I choose?

Use Website / Blog for articles, recipes, tutorials, and guides. Use Shopify Store for Shopify product pages. Use Etsy Shop for Etsy shop products, and enter the shop URL rather than a listing URL.

Why are Shopify and Etsy profiles image-only?

Product listings usually need product-focused image pins. Infographics are better for educational website content where there is enough structured material for a useful chart, checklist, comparison, or step-by-step visual.

How many pins can I generate?

• Monthly pins: Starter includes 600 pins/month, Pro includes 2,000 pins/month, and Agency includes 4,000 pins/month.
• Batch size: Up to 50 pins per batch (generation) or per schedule call.
• Free trial: 10 generated pins.
• Cycles: Limits reset monthly on your billing date.
• No Rollover: Unused included generations do not carry over to the next month.
• Extra generations: Generation packs are available from the Dashboard when you need more volume.

Can I schedule pins to multiple boards?

Yes. When scheduling, you can select multiple boards. Pins are distributed across the selected boards. Use shuffle modes (Auto, Board, Random) to control the distribution.

What happens to my pins if I disconnect Pinterest?

Your scheduled pins are preserved in PinBuilds. If you reconnect the same Pinterest account, pending pins will resume publishing automatically. Disconnecting does not delete any data.

Does the free trial include scheduling?

Yes, the free trial includes 10 generated pins and direct Pinterest scheduling during the trial period.

Is there a WordPress plugin?

Yes. The PinBuilds WordPress Plugin lets you automatically generate and schedule pins for every new post you publish. Install it, connect your API key, and it handles everything in the background. See the WordPress Plugin docs for details.

Is there a REST API?

Yes. PinBuilds provides a REST API for external integrations. Create an API key in Settings and use it to generate pins, check usage, and manage scheduling programmatically. See the API docs for details.

Can I use PinBuilds from Codex, Claude Code, Cursor, Hermes Agent, or Copilot?

Yes. PinBuilds has a remote MCP endpoint at /api/mcp for AI agents and coding assistants. It works with Codex, Claude Code, Cursor, VS Code/GitHub Copilot, Windsurf, Hermes Agent, Gemini CLI, ChatGPT Apps, and generic MCP clients. See the MCP & Agent Tools docs for setup templates.

Why does my MCP client say the API key is missing?

Make sure the client sends:

Authorization: Bearer pb_live_your_key_here

If your config uses ${PINBUILDS_API_KEY}, confirm that environment variable is available to the app or terminal that launches the MCP client.

Where do I configure scheduling settings?

All scheduling settings (pins per day, time window) and generation settings (generation mode, overlay, styles, pins per post) are managed on the Settings page. The Scheduler page shows these as read-only.