Skip to main content

​
Preview Connection Errors

Weaverse Studio preview loading failed error state
When working with Weaverse Studio, you may encounter preview connection errors that prevent the live preview from loading. This guide helps you quickly diagnose and resolve these issues.

​
Common Error Types

​
CONNECTION_TIMEOUT

Symptom: Preview shows “Unable to connect to preview server” after waiting 5+ seconds. Common Causes:
  • Development server not running
  • Server running on wrong port
  • Firewall blocking connection
  • Network connectivity issues
Quick Fixes:
  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
Quick Test: Open http://localhost:3456 in your browser. If it loads, the server is running correctly and the issue is with Studio configuration.

​
NO_WEAVERSE_CONTENT

Symptom: The preview loads, but Studio shows “No Weaverse content on this page yet” with setup guidance — not a connection error. The URL responded; it just has no Weaverse sections for Studio to edit.
This is a normal, recoverable state — not a broken preview. Studio stays connected on any page it can reach (including 404s and routes without Weaverse content) so it can tell you why there’s nothing to edit, instead of falsely reporting “Connection lost”. Requires @weaverse/hydrogen 5.16.3+ in your theme.
Common Causes:
  • 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
How to set it up:
  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 
    npm install @weaverse/hydrogen@latest
# or
pnpm add @weaverse/hydrogen@latest
If you just created a page, make sure it uses the Weaverse page template and has sections configured. See the Rendering Weaverse Pages guide for complete implementation details.

​
INVALID_URL

Symptom: Preview shows “Invalid preview URL” immediately. Common Causes:
  • Malformed URL in project settings
  • Missing protocol (http/https)
  • Invalid characters in URL
  • Localhost URL when expecting production
Quick Fixes:
  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

Symptom: Preview shows “Authentication required” or login prompt. Common Causes:
  • Password-protected development server
  • Shopify authentication required
  • Proxy/VPN requiring credentials
  • Corporate network restrictions
Quick Fixes:
  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

Symptom: Browser console shows CORS policy errors. Common Causes:
  • Missing CORS headers in development server
  • Incorrect origin configuration
  • Browser security restrictions
  • Proxy/middleware blocking requests
Quick Fixes:
  1. Configure Content Security Policy (CSP) Weaverse requires proper CSP configuration to allow iframe embedding. Update your entry.server.tsx: 
    // entry.server.tsx
import { createContentSecurityPolicy } from "@shopify/hydrogen";
import { getWeaverseCsp } from "~/weaverse/csp";

export default async function handleRequest(request, responseStatusCode, responseHeaders, remixContext, context) {
  const { nonce, header, NonceProvider } = createContentSecurityPolicy({
    ...getWeaverseCsp(request, context),
    shop: {
      checkoutDomain: context.env?.PUBLIC_CHECKOUT_DOMAIN || context.env?.PUBLIC_STORE_DOMAIN,
      storeDomain: context.env?.PUBLIC_STORE_DOMAIN,
    },
  });

  // Use Report-Only mode for development
  responseHeaders.set("Content-Security-Policy-Report-Only", header);
  // ...
}
  2. Verify Weaverse hosts are allowed Check your CSP configuration includes Weaverse domains: 
    // ~/weaverse/csp.ts (or similar)
export function getWeaverseCsp(request: Request, context: AppLoadContext) {
  let weaverseHosts = ["*.weaverse.io", "*.shopify.com", "*.myshopify.com"];

  return {
    defaultSrc: [...weaverseHosts],
    connectSrc: [...weaverseHosts],
    styleSrc: weaverseHosts,
    frameAncestors: ["*"], // Required for Studio embedding
  };
}
  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
See the Content Security Policy guide for complete CSP configuration details and best practices.
Production Note: Never use cors: true in production. Configure specific origins for your Weaverse Studio domain. Use Content-Security-Policy-Report-Only during development to monitor violations before enforcing.

​
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

The preview uses PostMessage/RPC for Studio communication: 
// Check if Weaverse is loaded in preview
window.weaverseStudio?.version // Should return version number

​
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

If you’ve tried all troubleshooting steps and still experiencing issues:
  1. Check System Status
  2. Community Support
  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 18+ (LTS recommended)
    • Check with node --version
  4. Monitor terminal output
    • Watch for server errors
    • Note the actual port being used
    • Check for build warnings

​
Common Configuration

Recommended vite.config.ts for preview: 
import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    port: 3456,
    cors: true,
    host: 'localhost',
    strictPort: false, // Try next port if 3456 is busy
  },
})
Recommended project settings:
  • Preview URL: http://localhost:3456
  • Auto-reload: Enabled
  • HTTPS: Disabled for local development
Still having issues? The preview error overlay in Weaverse Studio provides real-time troubleshooting suggestions specific to your error type. Click the Documentation button in the error overlay for context-specific help.