Troubleshooting Guide
Understanding AI and How Storefront.dev Works
Before diving into troubleshooting, it's helpful to understand how AI works within storefront.dev. We've equipped the AI with powerful toolsets including access to your Shopify catalog, brand guidelines, and various code libraries. However, AI operates probabilistically - it makes decisions based on patterns and context, which means:
- AI can be selective: Even though we've given it access to your brand assets and Shopify data, it might choose to use stock images or generic styling instead
- Instructions aren't guarantees: We prompt the AI to follow best practices (like proper image markup), but it's not 100% reliable
- Context matters: The AI performs better with clear, specific instructions and examples
- Iteration is normal: You may need to refine your prompts or provide additional guidance to get the desired result
Think of the AI as a skilled designer who has access to all your brand materials but might need specific direction to understand exactly what you want.
Common Issues and Solutions
1. Broken Image Links
What's happening: Images aren't loading in your preview, showing broken image icons or placeholder text.
Why it happens:
- The AI generated code without proper image markup
- The image source (Imgur, Unsplash, Pexels) no longer exists
- Image URLs have expired or been moved
Solutions:
Try this prompt first:
The images in my preview aren't loading properly. Can you check the image markup and ensure all images have proper alt text and valid URLs? Please use a different image service if the current ones aren't working.
For Shopify-specific images:
The images aren't pulling from my Shopify store. Please make sure to search my Shopify catalog for product images instead of using stock photos. I want to showcase my actual products.
When to contact support: If you've tried the above prompts and images still aren't loading from your Shopify store, email info@storefront.dev
2. AI Isn't Following Your Brand Guidelines
What's happening: The generated design doesn't match your brand colors, fonts, or style guidelines.
Why it happens:
- Brand guidelines weren't uploaded before starting the chat
- Guidelines were uploaded mid-conversation (they only apply to new chats)
- AI chose to interpret guidelines differently than expected
Solutions:
First, verify your setup:
- Ensure your brand guidelines are uploaded in your account
- If you uploaded them after starting this chat, you'll need to start a new conversation
Use this prompt to reinforce brand adherence:
Please refer to my uploaded brand guidelines and ensure this design matches my brand identity. Specifically:
- Use my brand colors throughout the design
- Apply my specified fonts and typography
- Follow my brand's visual style and tone
- Use imagery that aligns with my brand aesthetic
- Incorporate any logos or brand elements I've provided
Can you update the current design to better reflect these brand requirements?
If the AI is still not following guidelines:
I notice the design still doesn't match my brand guidelines. Can you:
- Review my uploaded brand document again
- Point out where you're applying my brand colors, fonts, and style
- Explain any choices that differ from my guidelines
- Make specific updates to align with my brand requirements
When to contact support: If the AI consistently ignores your brand guidelines after multiple attempts, contact info@storefront.dev.
3. Not Searching Your Shopify Catalog
What's happening: The AI is using generic product images instead of your actual Shopify products.
Why it happens:
- Shopify connection isn't properly established
- AI defaulted to stock imagery instead of searching your catalog
- Search parameters weren't specific enough
Solutions:
First, verify your Shopify connection is active
Use this prompt to redirect to your catalog:
Please search my Shopify product catalog for relevant products instead of using stock images. I want this storefront to showcase my actual products with their real images, descriptions, and pricing. Can you pull products that match [specific category/theme] from my store?
For specific product requests:
I want to feature specific products from my Shopify store. Please search for:
- [Product name or category 1]
- [Product name or category 2]
- [Product name or category 3]
Use the actual product images, titles, and descriptions from my Shopify catalog.
When to contact support: If your Shopify connection appears broken or products aren't being found, email info@storefront.dev
4. Stuck on "Building" Status
What's happening: The generation process seems frozen on "building" and won't complete.
Why it happens:
- Technical timeout occurred
Solutions:
Note: Currently there's no stop button to cancel a build in progress, but we're adding one soon. For now, if you're stuck on building, you'll want to 1) contact support at info@storefront.dev and 2) start a new chat to continue working.
If the build is stuck:
- Copy your entire conversation
- Start a new chat
- Paste the conversation history / add relevant screenshots
- Add: "This is my conversation history. Please continue from where we left off."
Alternative approach - copy paste your conversation into ChatGTP or Claude.ai with this prompt:
Can you summarize our conversation so far, including:
- The type of storefront we're building
- Key design decisions we've made
- Current status and what we were working on
I'll start a new chat with this summary to continue our work.
5. Preview Won't Load
What's happening: The visual preview panel is blank or shows an error instead of your storefront.
Why it happens:
- Generation got stuck (see issue #4 above)
- Code errors preventing proper rendering
Solutions:
Try regenerating the preview:
The preview isn't showing for me. Can you regenerate the code so that I can see a visual preview? Please make sure everything displays properly.
If preview is still blank:
I'm still not seeing any preview. Can you create a simplified version to test if the preview works, then build back up to the full design?
If you're a developer:
Open the developer console to inspect the error, and then provide that error back to the chat.
6. Features Not Working as Expected
What's happening: Interactive elements like sliders, buttons, or forms aren't functioning properly.
Why it happens:
- Missing JavaScript dependencies
- CSS conflicts affecting functionality
- Code implementation issues
Solutions:
For specific functionality issues:
My [slider/button/form/navigation] isn't working properly. [Describe the specific issue]. Can you fix this functionality? I'm attaching a screenshot showing the current behavior.
For performance issues:
The [specific feature] is reacting too slowly and feels unresponsive. Can you optimize it to be more responsive and smooth? Please make sure it works well on both desktop and mobile.
7. AI Doesn't Implement Requested Changes
What's happening: You ask for specific fixes, but they don't seem to be applied to the design.
Why it happens:
- Too many requests given at once, causing the AI to miss some
- Instructions weren't specific enough
- AI misunderstood the request
Solutions:
Make requests one at a time:
Let's focus on one change at a time. First, can you [specific single request]? Once that's working, I'll ask for the next change.
Be specific with screenshots:
I'm still seeing [specific issue]. I'm attaching a screenshot of what I'm currently seeing. Can you compare this to what I requested and make the necessary updates?
Follow up if changes aren't visible:
I don't see the changes I requested in the preview. Can you:
- Confirm you've made the changes to [specific element]
- Point out where I should see the differences
- Regenerate the preview if needed
8. Incorrect Imagery Issues
What's happening: The AI isn't using the images you specified or requested.
Why it happens: This breaks down into several scenarios:
8a. Uploaded Images Not Being Used
What's happening: You upload an image to the chat, but the AI recreates it instead of using your actual image.
Why this happens: This is intentional for privacy protection. When you upload images, the chat can see them, but the preview/code doesn't have access to prevent your image URLs from becoming public.
Solution: If you want to change this privacy setting, contact info@storefront.dev
8b. Shopify Images Not Loading
Solutions:
Check your connection first, then try:
Please search my Shopify catalog for [specific product or category] and use those actual product images. Don't use stock photos - I want my real products featured with their original images and details.
9. Slider Issues
What's happening: Image carousels or content sliders aren't working smoothly or at all.
Why it happens:
- Using unreliable slider libraries
- Missing JavaScript dependencies
- CSS conflicts
Solutions:
Request specific, reliable libraries:
The slider isn't working well. Can you rebuild it using one of these reliable libraries:
- Swiper.js
- Glide.js
- Splide.js Please make sure it's responsive and works smoothly on both desktop and mobile.
For customization:
Can you make the slider:
- Auto-play every [X] seconds
- Show [number] slides at once on desktop
- Show [number] slides on mobile
- Include navigation arrows and dots
- Have smooth transitions
10. Text Visibility Issues
What's happening: Text is hard to read or completely invisible.
Why it happens:
- Text color matches or is too similar to background
- Insufficient contrast ratios
- Transparency issues
Solutions:
Fix contrast issues:
Some text is hard to read because it's too light against the background. Can you:
- Increase the contrast between text and background
- Make sure all text meets accessibility standards
- Add background overlays or shadows where needed to improve readability
Specific color adjustments:
Please make the [header/body/button] text [darker/lighter/different color] so it stands out better against the [specific background element]. Ensure the text is easily readable.
11. Image Upload and Usage
What's happening: When you upload images to the chat, the AI tries to recreate them instead of using the actual files.
Why it happens: This is a privacy feature. Your uploaded images remain in the chat but aren't made publicly accessible in the generated code.
What you can do:
- Describe the image and ask the AI to find similar stock photos
- If you need your exact images used, contact info@storefront.dev to discuss changing privacy settings
12. Mobile Responsiveness Issues
What's happening: The design looks poor on mobile devices.
Why it happens:
- Desktop-first design approach
- Missing responsive CSS rules
- Layout not optimized for smaller screens
Solutions:
Test mobile view:
- Resize your browser window to simulate mobile
- Take screenshots of issues you see
Request mobile optimization:
The mobile version needs improvement. Can you:
- Make the layout stack properly on mobile screens
- Ensure text is readable without zooming
- Make buttons and links easy to tap
- Optimize images for mobile loading
- Test all functionality works on touch devices
Use reference examples:
I'm attaching screenshots of mobile experiences I like. Can you apply similar mobile styling and layout principles to make my storefront work better on phones and tablets?
13. Code Errors Taking Over
What's happening: Error messages or code appears in your preview instead of the design.
Why it happens:
- Syntax errors in generated code
- Missing dependencies
- Code conflicts
Solutions:
I'm getting a code error in my preview instead of seeing the design. Here's the error message I'm seeing: [paste the error]. Can you fix this code issue and restore the proper preview?
If the error persists:
The error is still showing. Can you create a fresh version of this section/page without the problematic code and ensure everything displays properly?
14. "Error While Processing Your Request"
What's happening: You receive a generic error message when trying to generate or update your storefront.
Why it happens:
- Message limit reached for this chat
- Server timeout or technical issues
Solutions:
If you suspect message limits:
- Copy your entire conversation
- Start a new chat
- Paste the conversation
- Continue from where you left off
Alternative - get a summary (possible once we've implemented a stop button, or you can use another AI tool like ChatGTP to summarize):
Can you create a detailed summary of our storefront project including:
- Design decisions made
- Current features and layout
- Brand guidelines applied
- Any custom requirements
- Next steps needed
I'll use this summary to start a new chat and continue our work.
15. Generation Complete But No Preview
What's happening: The AI says it's finished, but you don't see any visual preview.
Solutions:
You mentioned the generation is complete, but I'm not seeing any preview. Can you:
- Make sure the preview is properly generated
- Check if there are any code errors preventing the display
- Regenerate the preview if needed
General Troubleshooting Tips
Before You Start
- Upload brand guidelines before beginning your chat
- Ensure your Shopify connection is active
- Have example images or references ready
Communication Best Practices
- Be specific in your requests
- Make one change at a time for complex updates
- Include screenshots when reporting issues
- Provide examples of what you want to achieve
When to Contact Support
Email info@storefront.dev if you experience:
- Persistent Shopify connection issues
- Repeated failures to follow brand guidelines
- Technical errors that prompts can't resolve
- Need to change privacy settings for image usage
Getting Better Results
- Start with simple requests and build complexity
- Use clear, descriptive language
- Provide visual references when possible
- Be patient - AI may need iteration to get things right
For Developers
If you have technical expertise and want to troubleshoot code-level issues:
Code Error Debugging
- Copy/paste error messages from the browser console
- Inspect the generated HTML/CSS/JavaScript for syntax issues
- Check for missing dependencies or library conflicts
Manual Code Review
- Examine image markup for proper src and alt attributes
- Verify CSS selectors and responsive breakpoints
- Check JavaScript event handlers and library implementations
Advanced Troubleshooting
- Test individual components in isolation
- Validate HTML structure and semantic markup
- Debug mobile responsiveness using browser dev tools