​

Preview Connection Errors

​

Common Error Types

​

CONNECTION_TIMEOUT

• Development server not running
• Server running on wrong port
• Firewall blocking connection
• Network connectivity issues

1. Start your development server
   npm run dev
   # or
   pnpm dev
   # or
   yarn dev
   
2. Check the server is running on the correct port
   • Default port: 3456
   • Verify in your terminal output: Server running on http://localhost:3456
   • Check project settings in Weaverse Studio for configured preview URL
3. Verify network connectivity
   • Try opening the preview URL directly in your browser
   • Check if localhost resolves: ping localhost
   • Ensure no VPN/proxy interfering with local connections
4. Check firewall settings
   • Allow Node.js through your firewall
   • Temporarily disable firewall to test (macOS: System Settings → Network → Firewall)
   • Whitelist port 3456 in your security software

​

NO_WEAVERSE_CONTENT

• No page or template has been created/assigned for this route yet
• The underlying Shopify resource (collection, product, article) doesn’t exist, or isn’t published to your Headless / Hydrogen sales channel — the storefront route then returns a 404 with no content to edit
• The route doesn’t render <WeaverseHydrogenRoot />
• Missing or outdated @weaverse/hydrogen package

1. Create or assign a page for this route
   • Open the page selector in the Studio top bar and create/assign a page for the current URL
   • Add at least one section, then Save
2. For a Shopify resource page, confirm the resource exists and is published
   • In Shopify admin, verify the collection/product/article in the URL exists
   • Publish it to your Headless (Hydrogen) sales channel — an unpublished resource returns a 404, so the storefront renders its not-found page with no Weaverse content
   • Open the URL directly in your browser: a 404 there confirms the Shopify resource, not Weaverse, is missing
3. Verify the route renders Weaverse content
   • The route loader should call weaverse.loadPage() and the route should render <WeaverseHydrogenRoot />
   • Ensure components are registered in ~/weaverse/components.ts (or ~/app/weaverse/components.ts in the Pilot template)
   • Restart the dev server after adding new components
4. Confirm the page type is supported
   • Supported types: PRODUCT, COLLECTION, PAGE, BLOG, ARTICLE, INDEX, CUSTOM
   • Some routes (search, cart, account) use native Shopify components and aren’t Weaverse pages
5. Update Weaverse if needed
   # Hydrogen 2026.10 and later
   npm install @weaverse/hydrogen@^6
   # Classic Hydrogen (2026.4 and earlier)
   npm install @weaverse/hydrogen@^5
   
   @weaverse/hydrogen@latest installs v6, which requires Hydrogen 2026.10. To move a classic theme to v6, follow the v6 migration guide.

​

INVALID_URL

• Malformed URL in project settings
• Missing protocol (http/https)
• Invalid characters in URL
• Localhost URL when expecting production

1. Check project preview URL settings
   • Go to Project Settings in Weaverse Studio
   • Verify preview URL format: http://localhost:3456 (development)
   • Ensure no trailing slash or extra characters
2. Validate URL format
   • Must include protocol: http:// or https://
   • Use localhost not 127.0.0.1 for local development
   • Check for typos in domain name
3. Reset preview URL
   • Delete current preview URL
   • Enter fresh URL: http://localhost:3456
   • Save and refresh Studio

​

AUTH_REQUIRED

• Password-protected development server
• Shopify authentication required
• Proxy/VPN requiring credentials
• Corporate network restrictions

1. Remove password protection temporarily
   • Disable HTTP authentication in development
   • Check for .htaccess or auth middleware
   • Ensure dev server allows unauthenticated requests
2. Configure Shopify authentication
   • Ensure valid session tokens
   • Check Shopify app credentials
   • Verify OAuth flow is working
3. Bypass network restrictions
   • Test on different network (mobile hotspot)
   • Whitelist localhost in corporate firewall
   • Contact IT if on restricted network

​

CORS_ERROR

• Missing CORS headers in development server
• Incorrect origin configuration
• Browser security restrictions
• Proxy/middleware blocking requests

1. Check the CSP for Studio’s sources Studio embeds your storefront in an iframe and injects its bridge script from the weaverseHost URL without a nonce. In design mode (the URL has a weaverseHost query parameter), your CSP must include:
   • frame-ancestors *
   • The Weaverse hosts (*.weaverse.io and the weaverseHost value) in script-src, connect-src, and style-src
   • 'unsafe-eval' in script-src, so the bridge can rebuild schema condition functions
   Pilot’s getWeaverseCsp (app/weaverse/csp.ts) sets all of these:
   // app/weaverse/csp.ts (excerpt)
   const weaverseHost =
     url.searchParams.get("weaverseHost") || env.WEAVERSE_HOST;
   const isDesignMode = url.searchParams.get("weaverseHost");
   const weaverseHosts = ["*.weaverse.io", "*.shopify.com", "*.myshopify.com"];
   if (weaverseHost) {
     weaverseHosts.push(weaverseHost);
   }
   // ...connectSrc, styleSrc and scriptSrc all spread ...weaverseHosts
   if (isDesignMode) {
     updatedCsp.frameAncestors = ["*"];
     (updatedCsp.scriptSrc as string[]).push("'unsafe-eval'");
   }
   
2. Make sure script-src lists every script origin Once script-src is set, it replaces default-src for scripts. A scriptSrc that lists only https://cdn.shopify.com blocks the Studio bridge as soon as the header is enforced, even if the Weaverse hosts are in defaultSrc. Look for violates the following Content Security Policy directive in the console and add the blocked origin to the directive it names. On Hydrogen 2026.10 the theme builds the CSP header itself, since Hydrogen no longer ships createContentSecurityPolicy. See the Content Security Policy guide for the setup and a rollout checklist.
3. Enable CORS for local development
   // vite.config.ts
   server: {
     cors: true,
     // or more specific:
     cors: {
       origin: ['https://studio.weaverse.io', 'https://*.weaverse.io'],
       credentials: true
     }
   }
   
4. Restart development server
   • Stop server (Ctrl+C)
   • Clear cache: rm -rf .cache
   • Restart: npm run dev

​

Advanced Troubleshooting

​

Check Browser Console

1. Open browser DevTools (F12 or Cmd+Option+I)
2. Go to Console tab
3. Look for red error messages
4. Copy error messages for support

​

Network Inspector

1. Open DevTools → Network tab
2. Refresh preview
3. Look for failed requests (red status)
4. Check request/response headers
5. Note status codes (404, 500, etc.)

​

Verify RPC Communication

// Check whether the Weaverse storefront runtime booted in the preview.
// @weaverse/hydrogen stores runtimes by Weaverse page ID.
const runtime = Object.values(window.__weaverses ?? {})[0]
runtime?.sdkVersion // e.g. "6.1.0" when a runtime is mounted
runtime?.isDesignMode // true when the page is rendered inside Studio

window.__weaverses // Record<pageId, Weaverse runtime>

​

Clear Studio Cache

1. In Weaverse Studio, press Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
2. This forces a hard refresh and clears cached preview state

​

Test with Different Browser

• Try Chrome, Firefox, Safari
• Disable browser extensions
• Use incognito/private mode
• Brave Browser Users: Disable “Shields” (ad blocker) for Studio domain
  • Click the shield icon in the address bar
  • Turn off “Shields” for studio.weaverse.io and your preview domain
  • Brave’s aggressive ad/tracker blocking can interfere with iframe communication

​

Getting Help

1. Check System Status
   • Visit status.weaverse.io for known issues
2. Community Support
   • Join Weaverse Discord
   • Search GitHub Discussions
3. Contact Support
   • Email: support@weaverse.io
   • Include:
     • Error type from preview overlay
     • Browser and OS version
     • Node.js version (node --version)
     • Package versions from package.json
     • Console error messages (screenshots)

​

Prevention Tips

​

Development Best Practices

1. Always run dev server before opening Studio
   npm run dev
   
2. Keep packages updated
   npm update @weaverse/hydrogen
   
3. Use recommended Node.js version
   • Node.js 22.18+ or 24.11+ for the current Pilot template
   • Check with node --version
4. Monitor terminal output
   • Watch for server errors
   • Note the actual port being used
   • Check for build warnings

​

Common Configuration

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    port: 3456,
    cors: true,
    host: 'localhost',
    strictPort: false, // Try next port if 3456 is busy
  },
})

• Preview URL: http://localhost:3456
• Auto-reload: Enabled
• HTTPS: Disabled for local development

​

Related Resources

• Development Setup Guide
• Weaverse Configuration Reference
• Theme Development Guide
• Component Registration