Skip to main content

Troubleshooting Common Issues

Troubleshooting comes in handy when you errors occur. Discover more.

Written by Dynamic Mockups Support
Updated over 2 months ago

Overview

This guide covers the most common issues you may encounter when using Dynamic Mockups, whether through the API, web application, or integrations.

Each issue includes the error message you'll see, what causes it, and how to fix it.

Quick Navigation:

  • API authentication errors (401)

  • Invalid UUID errors (422)

  • File format issues (400)

  • Server errors (500)

  • Web application issues

  • Integration problems

API Errors

Missing "Accept: application/json" Header

Issue: Receiving HTML responses or improperly formatted messages instead of JSON.

Cause: The API returns JSON-formatted responses. If your HTTP client doesn't specify that it accepts JSON, the server may return responses in an unexpected format.

Solution:

Always include the Accept: application/json header in every API request:

curl -X POST https://app.dynamicmockups.com/api/v1/renders \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"
```

**Required Headers for All Requests:**
```
Accept: application/json
Content-Type: application/json
x-api-key: YOUR_API_KEY

Required Headers for All Requests:

Accept: application/json Content-Type: application/json x-api-key: YOUR_API_KEY

(401) Missing or Invalid API Key

Error Response:

{   "message": "Unauthenticated." }

or

{   "message": "Unauthorized" }

Causes:

  • Missing x-api-key header in your request

  • Invalid or expired API key

  • API key not properly formatted

  • Using wrong authentication method

Solutions:

1. Verify API Key is Included:

Check that your request includes the x-api-key header:

headers: {
  'x-api-key': 'YOUR_API_KEY_HERE',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

2. Generate a New API Key:

  1. Log in to your Dynamic Mockups account

  2. Navigate to the API Dashboard

  3. Click "Create new API key"

  4. Copy the key and replace it in your code

3. Check Key Format:

API keys follow this format: prefix:hash

Example: bdf8301a-ef40-457d-8f2e-0d91e18726a0:d1c144ad6cbe665f680584d9a917a2a56c2ae07bd9ddc102cdd881604a159691

4. Verify Account Status:

Ensure your account is active and has available credits.

(422) Invalid Mockup UUID

Error Response:

{ "message": "The selected mockup uuid is invalid.", "errors": { "mockup_uuid": [ "The selected mockup uuid is invalid." ] } }

Causes:

  • Mockup UUID doesn't exist in your account

  • Typo in the UUID

  • Using a UUID from a different account

  • Mockup was deleted

Solutions:

Method 1: Copy UUID from Web Application

  1. Open the mockup in the Dynamic Mockups web application

  2. Look at the URL in your browser

  3. Copy the UUID from the URL

URL Format:

https://app.dynamicmockups.com/create/mockup/9ffb48c2-264f-42b9-ab86-858c410422cc                                            ↑ Mockup UUID ↑

Method 2: Use Get Mockups API

Retrieve all available mockups programmatically:

curl -X GET https://app.dynamicmockups.com/api/v1/mockups \
  -H "Accept: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Response will include:

  • All mockup UUIDs in your account

  • Mockup names and details

  • Available smart objects

Method 3: Check the Mockup Exists

  • Verify the mockup hasn't been deleted

  • Confirm you're using the correct account

  • Check that the mockup is in your templates library

Full Get Mockups API Documentation →

(422) Invalid Smart Object UUID

Error Response:

{ "message": "The selected smart_objects.0.uuid is invalid.", "errors": { "smart_objects.0.uuid": [ "The selected smart_objects.0.uuid is invalid." ] } }

Causes:

  • Smart Object UUID doesn't exist in the specified mockup

  • Typo in the UUID

  • Using a Smart Object from a different mockup

  • Mockup template changed and Smart Objects were modified

Solutions:

Method 1: Copy UUID from Web Application

  1. Open the mockup editor in the web application

  2. Look at the URL

  3. Copy the Smart Object UUID from the URL parameters

URL Format:

https://app.dynamicmockups.com/create/mockup/MOCKUP_UUID?smart_object=cc864498-b8d1-495a-9968-45937edf42b3                                                                         ↑ Smart Object UUID ↑

Method 2: Use Get Mockups API

The Get Mockups API returns complete mockup information including all available Smart Objects:

curl -X GET https://app.dynamicmockups.com/api/v1/mockup/MOCKUP_UUID \
  -H "Accept: application/json" \
  -H "x-api-key: YOUR_API_KEY"

Response includes:

{
  "data": {
    "uuid": "mockup-uuid-here",
    "name": "T-Shirt Mockup",
    "smart_objects": [
      {
        "uuid": "smart-object-uuid-1",
        "name": "Front Design",
        "type": "image"
      },
      {
        "uuid": "smart-object-uuid-2",
        "name": "Back Design",
        "type": "image"
      }
    ]
  }
}

Method 3: Verify Smart Object Belongs to Mockup

  • Each mockup has specific Smart Objects

  • Smart Object UUIDs are unique to their mockup

  • You cannot use a Smart Object UUID from one mockup in another

(400) Wrong File URL Extension Provided

Error Response:

{
  "success": false,
  "message": "Wrong file URL extension provided. svg is not supported. Supported values are: jpg, jpeg, png, webp, gif"
}

Cause: You're trying to use an unsupported file format for design assets.

Supported Formats:

  • JPG / JPEG

  • PNG

  • WEBP

  • GIF

Not Supported:

  • SVG (vector files)

  • PDF

  • AI (Adobe Illustrator)

  • PSD (use as template, not design asset)

  • BMP

  • TIFF

Solutions:

1. Convert Your File:

Convert SVG or other unsupported formats to PNG or JPG before uploading:

  • Use online converters (CloudConvert, Convertio)

  • Use design tools (Photoshop, Illustrator, Figma)

  • Use command-line tools (ImageMagick)

2. Export from Design Tools:

When exporting from design software:

  • Choose PNG for transparent backgrounds

  • Choose JPG for solid backgrounds

  • Set appropriate resolution (300 DPI for print)

3. Use Proper URLs:

Ensure your file URL points to an actual image file with the correct extension:

✅ Good: https://example.com/design.png
❌ Bad: https://example.com/design.svg
❌ Bad: https://example.com/design (no extension)

4. Check URL Accessibility:

  • Verify the URL is publicly accessible

  • Test the URL in a browser

  • Ensure no authentication is required

(500) Server Errors

Error Response:

{   "message": "Internal Server Error" }

or

HTTP 500 status code

Cause: Unexpected server-side error (not caused by your request).

This is NOT expected behavior and should be rare given our 99.9% reliability rate on AWS infrastructure.

Immediate Actions:

  1. Retry the Request:

    • Wait 30 seconds and try again

    • Server may have experienced temporary issue

  2. Check Status Page:

    • Visit our status page to see if there are known issues

    • Check for scheduled maintenance

  3. Contact Support:

If you consistently receive 500 errors:

  • Email: [email protected]

  • Slack: Join our community

  • Include:

    • Error message

    • Request payload (remove sensitive data)

    • Timestamp

    • API endpoint used

    • Expected behavior

We will resolve server issues as quickly as possible.

Web Application Issues

Can't Upload Designs

Symptoms:

  • Upload button not responding

  • File won't process

  • Upload gets stuck

Solutions:

✅ Check File Size: Maximum file size varies by plan (typically 25MB)

✅ Verify File Format: Use JPG, PNG, WEBP, or GIF

✅ Clear Browser Cache: Sometimes cached data causes issues

✅ Try Different Browser: Test in Chrome, Firefox, or Safari

✅ Check Internet Connection: Ensure stable connection for uploads

✅ Disable Browser Extensions: Ad blockers may interfere with uploads

Mockup Not Generating

Symptoms:

  • Generation appears to start but doesn't complete

  • Stuck on loading screen

  • No error message shown

Solutions:

✅ Check Credits: Ensure you have available credits in your account

✅ Verify Design File: Make sure your design file is valid and accessible

✅ Refresh the Page: Sometimes a simple refresh resolves the issue

✅ Try Smaller File: Large files may time out; try optimizing first

✅ Check Smart Object Configuration: Ensure design placement is configured correctly

Can't Find Mockup Template

Solutions:

✅ Use Search Function: Search by product name or scene type

✅ Check Category Filters: Ensure no filters are limiting results

✅ Browse All Categories: Template might be in unexpected category

✅ Try MockAnything AI: Generate custom mockups if template library doesn't have what you need

✅ Upload Custom Template: Use your own Photoshop file

Export/Download Not Working

Symptoms:

  • Download button doesn't respond

  • File downloads but is corrupted

  • Export never completes

Solutions:

✅ Check Browser Download Settings: Verify downloads aren't blocked

✅ Disable Pop-up Blockers: May prevent download dialogs

✅ Try Right-Click → Save As: Alternative download method

✅ Clear Browser Cache: Remove potentially corrupted cache

✅ Use Different Browser: Test if browser-specific issue

Integration Issues

Shopify Integration Not Working

Solutions:

✅ Verify App Installation: Check app is fully installed and activated

✅ Re-authenticate: Disconnect and reconnect your Dynamic Mockups account

✅ Check Permissions: Ensure app has necessary Shopify permissions

✅ Update Theme: Confirm theme is compatible (Online Store 2.0)

✅ Contact Support: We can check integration logs

Shopify Integration Guide →

WooCommerce Plugin Issues

Solutions:

✅ Update Plugin: Ensure you're using the latest version

✅ Check WordPress Version: Must be 4.7 or higher

✅ Verify PHP Version: Requires PHP 7.0 or higher

✅ Check WooCommerce Status: WooCommerce must be active

✅ Deactivate Conflicting Plugins: Test with other plugins disabled

WooCommerce Integration Guide →

Zapier/Make Integration Errors

Solutions:

✅ Verify API Key: Ensure API key is correctly entered

✅ Test Connection: Use built-in connection test feature

✅ Check Zap/Scenario Status: Ensure automation is turned on

✅ Review Action Configuration: Verify all required fields are filled

✅ Check Credit Balance: Ensure sufficient credits available

Zapier Integration Guide →

Make Integration Guide →

Embedded Editor Not Loading

Solutions:

✅ Verify Website Key: Check key is correct and active

✅ Check iframe Dimensions: Minimum 600px height recommended

✅ Ensure JavaScript Enabled: Required for interactive functionality

✅ Load SDK Script First: Script must load before initialization

✅ Check Browser Console: Look for error messages

✅ Test in Incognito Mode: Rule out extension conflicts

Embeddable Editor Guide →

General Troubleshooting Tips

Check Your Credits

Many issues are caused by depleted credits:

  1. Log in to Dynamic Mockups

  2. Check dashboard sidebar for credit balance

  3. Visit Subscription page for detailed usage

  4. Upgrade or purchase top-up if needed

Verify Account Status

Ensure your account is in good standing:

  • Subscription is active

  • Payment method is valid

  • No billing issues

  • Account hasn't been suspended

Clear Cache and Cookies

Often resolves web application issues:

  1. Open browser settings

  2. Clear browsing data

  3. Select cache and cookies

  4. Restart browser

Update Browser

Outdated browsers may cause compatibility issues:

Supported Browsers:

  • Chrome 90+

  • Firefox 88+

  • Safari 14+

  • Edge 90+

Check Internet Connection

Slow or unstable connections cause:

  • Upload failures

  • Generation timeouts

  • Export problems

Test:

  • Run speed test

  • Check for packet loss

  • Try different network if available

Try Incognito/Private Mode

Helps identify if extensions or cache are causing issues:

  • Chrome: Ctrl+Shift+N (Cmd+Shift+N on Mac)

  • Firefox: Ctrl+Shift+P (Cmd+Shift+P on Mac)

  • Safari: Cmd+Shift+N

Getting Help

Email: [email protected]

  • Include detailed description

  • Attach screenshots if relevant

  • Provide error messages

  • Mention steps already tried

Slack Community: Join here

  • Chat with other users

  • Get help from the team

  • Share solutions

Provide Helpful Information

When reporting issues, include:

For API Issues:

  • Endpoint used

  • Request payload (remove sensitive data)

  • Full error response

  • Timestamp

  • API key (first 10 characters only)

For Web Application Issues:

  • Browser and version

  • Operating system

  • Screenshots

  • Steps to reproduce

  • Expected vs. actual behavior

For Integration Issues:

  • Platform name and version

  • Integration method

  • Configuration details

  • Error messages

Prevention Tips

✅ Test with Sandbox First: Use sandbox credentials before production

✅ Implement Error Handling: Code should handle API errors gracefully

✅ Monitor Credit Usage: Track consumption to avoid interruptions

✅ Keep Software Updated: Update plugins, apps, and dependencies

✅ Save API Keys Securely: Store keys in environment variables

✅ Read Documentation: Review docs before implementation

✅ Use API Playground: Test requests in playground first

✅ Set Up Webhooks: Get notified of issues automatically

Additional Resources

Related Articles
Bulk Render API: Automate Large Scale Mockup Generation
Zapier Integration Guide
Dynamic Mockups API: Complete Guide
Photoshop Integration
MCP Server for AI-Assisted Development
Did this answer your question?