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:

Start your development server

npm run dev
# or
pnpm dev
# or
yarn dev

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
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
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: Preview loads but shows “We couldn’t find Weaverse content on this page.” Common Causes:

Weaverse components not installed in theme
Wrong page selected (non-Weaverse page)
Theme not properly configured
Missing @weaverse/hydrogen package

Quick Fixes:

Verify Weaverse is installed in your theme

# Check package.json includes:
npm list @weaverse/hydrogen

Ensure page is a Weaverse-enabled route
- Check if the page uses Weaverse components
- Navigate to a known Weaverse page (e.g., homepage)
- Verify route file includes Weaverse setup with loadPage() and <WeaverseContent />
Check component registration
- Ensure all Weaverse components are properly registered in ~/weaverse/components.ts (or ~/app/weaverse/components.ts in Pilot template)
- Use namespace imports: import * as ComponentName from "~/sections/component"
- Restart dev server after adding new components
Verify correct page type
- Ensure you’re using a supported Weaverse page type: PRODUCT, COLLECTION, PAGE, BLOG, ARTICLE, INDEX, or CUSTOM
- Some pages (search, cart, account) may not use Weaverse at all - they use native Shopify components instead
- Check loader uses correct type: weaverse.loadPage({ type: "PRODUCT", handle })

Reinstall Weaverse packages

npm install @weaverse/hydrogen@latest
# or
pnpm add @weaverse/hydrogen@latest

If you just created a new page, make sure it’s using the Weaverse page template and has Weaverse components 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:

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
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
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:

Remove password protection temporarily
- Disable HTTP authentication in development
- Check for .htaccess or auth middleware
- Ensure dev server allows unauthenticated requests
Configure Shopify authentication
- Ensure valid session tokens
- Check Shopify app credentials
- Verify OAuth flow is working
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:

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);
  // ...
}

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
  };
}

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
  }
}

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

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

Network Inspector

Open DevTools → Network tab
Refresh preview
Look for failed requests (red status)
Check request/response headers
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

In Weaverse Studio, press Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
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:

Check System Status
- Visit status.weaverse.io for known issues
Community Support
- Join Weaverse Discord
- Search GitHub Discussions
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

Always run dev server before opening Studio
```
npm run dev
```
Keep packages updated
```
npm update @weaverse/hydrogen
```
Use recommended Node.js version
- Node.js 18+ (LTS recommended)
- Check with node --version
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.

Resources

Troubleshooting

Community & Updates

Preview Connection Errors

Preview Connection Errors

Common Error Types

CONNECTION_TIMEOUT

NO_WEAVERSE_CONTENT

INVALID_URL

AUTH_REQUIRED

CORS_ERROR

Advanced Troubleshooting

Check Browser Console

Network Inspector

Verify RPC Communication

Clear Studio Cache

Test with Different Browser

Getting Help

Prevention Tips

Development Best Practices

Common Configuration

Resources

Troubleshooting

Community & Updates

​Preview Connection Errors

​Common Error Types

​CONNECTION_TIMEOUT

​NO_WEAVERSE_CONTENT

​INVALID_URL

​AUTH_REQUIRED

​CORS_ERROR

​Advanced Troubleshooting

​Check Browser Console

​Network Inspector

​Verify RPC Communication

​Clear Studio Cache

​Test with Different Browser

​Getting Help

​Prevention Tips

​Development Best Practices

​Common Configuration

​Related Resources

Preview Connection Errors

Common Error Types

CONNECTION_TIMEOUT

NO_WEAVERSE_CONTENT

INVALID_URL

AUTH_REQUIRED

CORS_ERROR

Advanced Troubleshooting

Check Browser Console

Network Inspector

Verify RPC Communication

Clear Studio Cache

Test with Different Browser

Getting Help

Prevention Tips

Development Best Practices

Common Configuration

Related Resources