Troubleshooting tasks

This guide covers common issues you might encounter with tasks and how to resolve them.

Failed Items

If individual items fail during processing:

1. Check the Error Message: Click on the failed item to see the specific error. Common errors include:
   • Image generation failures (model timeout, API errors)
   • Mockup generation issues (frame processing errors)
   • Etsy/Shopify publishing errors (authentication, validation)
2. Retry Failed Items: Use the "Retry Failed Items" button in the task progress view. This will restart failed items from the beginning.
3. Check Retry Count: Items show how many times they've been retried. If retries keep failing, the issue may be persistent.

Common Issues

Task Stuck in "Generating Locations"

If your task stays in this status for more than 2-3 minutes:

• Check your internet connection
• Verify your task name is clear and descriptive
• Try cancelling and recreating the task with a different name

Items Stuck in "Creating Mockup"

Mockup generation can take 30-60 seconds per item. If stuck longer:

• Check if the progress shows partial completion (e.g., "2/4")
• Wait up to 10 minutes—some frames take longer to process
• If no progress after 10 minutes, retry the failed items
• Verify your PSD frames are properly configured

Etsy Publishing Failures

If items fail during Etsy publishing:

• Verify your Etsy connection is active (check Settings → Integrations)
• Ensure you have proper Etsy permissions granted
• Check if your Etsy shop is in good standing
• Verify your shipping profile is configured
• Check for Etsy API rate limits (wait and retry)

Image Generation Failures

If AI image generation fails:

• Try a different AI model (some models may be temporarily unavailable)
• Check if you have sufficient credits
• Verify your prompt/task name isn't too vague
• Wait a few minutes and retry (API services may be experiencing issues)

Retrying Failed Items

To retry failed items:

1. Navigate to your task's progress view
2. Click the "Retry Failed Items" button (appears when there are failed items)
3. Confirm the retry action
4. Monitor the retry progress—items will restart from image generation

Note: Retrying starts items from the beginning. If an item completed image generation but failed at mockup creation, it will regenerate the image as well.

Cancelling Tasks

You can cancel a task while it's processing:

• Click "Cancel Task" in the task progress view
• Confirm the cancellation (this permanently deletes the task)
• Items currently processing will stop
• Completed items will be preserved until task deletion

Warning: Cancelling a task immediately stops all processing and deletes the task. This cannot be undone.

Best Practices to Avoid Issues

• Start Small: Test with 5-10 items before running large batches
• Check Connections: Verify Etsy/Shopify integrations before creating tasks
• Use Clear Names: Descriptive task names help GPT generate better locations
• Monitor Progress: Keep an eye on tasks to catch issues early
• Choose Reliable Models: Some AI models are more stable than others
• Verify Settings: Double-check your shipping profiles and preferences