Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
Troubleshooting & FAQ
Organized by symptom. Find your problem, check the likely causes, follow the fix steps.
1. Model Loading Issues
The 3D model doesn't appear (blank canvas)
Symptom: The <agent-3d> element renders but the canvas is empty or stays on the loading poster.
Likely causes:
- Network error fetching the GLB
- CORS headers missing on the GLB host
- File too large for the browser to parse in time
- Wrong file format
Fix steps:
- Open DevTools → Console (F12). Look for red errors, a failed fetch or a Three.js parse error will be logged there.
- Open DevTools → Network. Find the GLB request. Check the HTTP status code:
404: the URL is wrong. Verifysrcattribute.403/401: access is blocked. Make the file publicly readable.200with a CORS error in Console: see the CORS section below.
- Paste the GLB URL directly into a new browser tab. If it downloads or previews, the URL is valid.
- Check file size. Models over ~100 MB can cause timeouts on slow connections. Compress with Draco (5-10× mesh size reduction). See "Model loads slowly" under Performance.
- Verify the format. Only glTF 2.0 (
.glbor.gltf) is supported. glTF 1.0, OBJ, FBX, and USDZ are not. If you're exporting from Blender, use File → Export → glTF 2.0 with "Format: GLB".
"CORS error" in the console
Symptom: Console shows Access to fetch at '...' has been blocked by CORS policy.
Likely causes:
- The server hosting the GLB doesn't send CORS response headers.
Fix steps:
- Add
Access-Control-Allow-Origin: *to the response headers on the server that hosts your GLB. How to do this depends on your host:- Nginx:
add_header Access-Control-Allow-Origin *;in thelocationblock. - Apache:
Header set Access-Control-Allow-Origin "*"in.htaccess. - AWS S3 / CloudFront: Set a CORS policy on the bucket (allow all origins, GET method).
- Vercel / Netlify: Add a
headersrule in the config file.
- Nginx:
- If you can't modify the server, re-host the file somewhere that sends CORS headers: the platform's hosted storage (uploads via the Studio are CORS-configured automatically), or any CDN/bucket with a permissive CORS rule (Cloudflare R2, S3 + CORS policy). Note that the
key-proxyattribute is not a fetch proxy, it points the element at your LLM API-key proxy endpoint (so the key never reaches the client) and has no effect on GLB loading.
Model loads but textures are missing
Symptom: The model's geometry appears but surfaces are grey or untextured.
Likely causes:
- For
.gltf(JSON format): texture files aren't being served alongside the JSON file - Texture URLs inside the glTF JSON are broken
Fix steps:
- Open the file in a glTF viewer (e.g. gltf.report) to isolate the problem from the viewer itself.
- If using
.gltf(not.glb): texture PNG/JPG files must be served from the same origin as the JSON and referenced by relative path. The simplest fix is to re-export as.glb, this embeds all textures in one file. - If using
.glb: textures are embedded by default. If they're missing, the export settings may have excluded them. In Blender: tick "Include → Textures" when exporting.
Model loads but looks wrong (black material, wrong colors)
Symptom: Model appears but with black surfaces, missing reflections, or washed-out colors.
Likely causes:
- No environment map: metallic materials need a reflection source
- Metalness = 1.0 with no environment (renders black)
- Inverted normal map
Fix steps:
- Change the environment preset in the viewer panel. Metallic materials need an HDR environment to reflect.
- If the model is all-black: open it in Blender and check the material's Metallic value. A fully metallic material with no environment will be pitch black. Set Metallic to 0 or load an HDRI in the viewer.
- If lighting looks inverted: the normal map's G channel may be flipped (a common difference between DirectX and OpenGL conventions). Flip it in your 3D editor before re-exporting.
Draco-compressed model fails to load
Symptom: Model exported with Draco compression either shows an error or silently fails to load.
Likely causes:
- Content Security Policy blocking the Draco decoder WASM (loaded from CDN)
Fix steps:
- Check the Console for CSP violations mentioning
draco_decoder.wasmor the CDN hostname. - If CSP is blocking it, either add the CDN to your
script-srcandconnect-srcdirectives, or host the decoder yourself and setdracoDecoderPathon the viewer options.
2. Agent / LLM Issues
Agent doesn't respond to messages
Symptom: Chat input works but no reply appears. The agent is silent.
Likely causes:
brainattribute not set on<agent-3d>: without it, the element usesNullProvider(a no-op)- Missing or invalid
ANTHROPIC_API_KEY - Rate limit reached
Fix steps:
- Check the
brainattribute. The agent only activates LLM mode whenbrainis set to a model name:
Without this attribute,<agent-3d brain="claude-opus-4-7" ...></agent-3d>brain.providerdefaults tononeand the agent usesNullProvider, which returns empty responses silently. - Open DevTools → Network. Filter for
/api/chator/api/llm. Look at the response:401: the API key is missing or invalid.429: rate limited. Wait a minute and retry.500: server error. Check the server logs.
- Verify
ANTHROPIC_API_KEYis set in your server environment. On the production Cloud Run service:
Updating an env var rolls a new revision automatically. On a self-hosted fork, set it wherever your host reads environment variables and restart/redeploy.gcloud run services update three-ws-api --region us-central1 \ --update-env-vars ANTHROPIC_API_KEY=sk-ant-... - If you're calling the Anthropic API directly from the browser (not via a proxy), also set the
api-keyattribute on the element and note that this exposes your key to users.
Agent responds but says something off-topic
Symptom: The agent replies but ignores its role or answers questions it shouldn't.
Fix steps:
- Tighten the system prompt. A vague
instructionsfield produces vague behavior. Be explicit: "You are a guide for [product]. You only discuss [topic]. If asked about anything else, say you can't help with that." - Add a boundary statement to the instructions: "Never break character. Never discuss topics outside [domain]."
- If you're loading instructions from a
.mdfile viabrain.instructions, verify the file is being fetched correctly, check the Network panel for the.mdrequest.
Agent emotions not showing (no facial expression)
Symptom: Agent responds and speaks but the avatar's face doesn't change expression.
Likely causes:
- Model missing required morph targets
- Missing
HeadorNeckbone for head movement
Fix steps:
- Check the Console. The avatar module logs a warning if expected morph targets aren't found on load.
- Verify your GLB has morph targets named exactly as expected (case-sensitive). The emotion system maps to:
mouthSmile,mouthFrown,mouthOpen,cheekPuff,browInnerUp,browOuterUpLeft/browOuterUpRight,noseSneerLeft/noseSneerRight,eyeSquintLeft/eyeSquintRight,eyesClosed. These are the standard ARKit / humanoid avatar blendshape names. - For head tilt and lean, the skeleton needs a
HeadorNeckbone. Open the model in Blender and check the armature. - Confirm the avatar module is initialized: open DevTools Console and run
window.VIEWER?.agent_avatar. Ifundefined, the avatar layer didn't boot, check for earlier errors in the console.
Agent speaks but mouth doesn't move
Symptom: TTS audio plays but lips stay still.
Likely cause: The mouthOpen morph target is missing or misspelled.
Fix steps:
- Open the GLB in Blender → Object Data Properties → Shape Keys. Look for
mouthOpen(exact spelling, camelCase). - If the shape key exists but has a different name (e.g.
Mouth_Open,mouth_open), rename it tomouthOpenand re-export.
TTS not working (agent doesn't speak aloud)
Symptom: Agent sends text responses but no audio.
Likely causes:
- Browser blocking audio autoplay
- Browser doesn't support
SpeechSynthesis
Fix steps:
- Click somewhere on the page first. Browsers block audio autoplay until there's been a user interaction. After clicking, retry the message.
- Check browser support: run
'speechSynthesis' in windowin the Console. Iffalse, the browser doesn't support the Web Speech API. Try Chrome or Edge. - Check system volume and browser tab mute state.
ElevenLabs TTS not working
Symptom: ElevenLabs voice is configured but no audio plays, or audio falls back to browser TTS.
Fix steps:
- Open DevTools → Network. Filter for
/api/ttsorelevenlabs.io. Check the response:401:ELEVENLABS_API_KEYis missing or wrong.429: rate limited. The free tier allows 10,000 characters/month.422: voice ID is invalid. Verify thevoiceIdin your manifest or config.
- Confirm
ELEVENLABS_API_KEYis set in your server environment variables.
3. Embedding Issues
Embedded agent doesn't appear
Symptom: The page loads but the <agent-3d> element is invisible.
Likely causes:
- Script tag not loaded before the element
- CSP blocking the CDN
- SSR rendering the web component on the server (which has no
window)
Fix steps:
- Verify the
<script>tag loads before the<agent-3d>element in the DOM, or that it usesdefer/asynccorrectly. - Check the Console for CSP violations. The script origin (
https://three.ws) must appear in yourscript-srcpolicy (and inconnect-srcfor API and model fetches). - For Next.js: web components use browser APIs (
window,document,SpeechSynthesis) that don't exist server-side. Mark the component file with'use client'and disable SSR for the wrapper:import dynamic from 'next/dynamic'; const Agent3D = dynamic(() => import('./Agent3DWrapper'), { ssr: false });
Iframe embed shows "Refused to connect" or blocked by X-Frame-Options
Symptom: An iframe pointing at the agent URL shows an error instead of the agent.
Fix steps:
- Verify the
srcURL is correct: use the full HTTPS URL. - Do not use a URL that ends in
/editor/dashboard: those pages block framing for security. Use the agent's public embed URL (/agent/<id>/embed,/w/<widget-id>, or/widget#widget=<id>). - Only the dedicated embed routes send a
frame-ancestors *CSP header (set in the route table and applied by the server); regular pages sendframe-ancestors 'self'and will refuse to load in your iframe. If an embed route is being blocked, the block is coming from the host page's own CSP, the agent's embed policy (domain allowlist), or a browser extension.
postMessage not working
Symptom: Messages sent to the agent iframe via postMessage don't produce a reaction.
Fix steps:
Target the correct origin:
'https://three.ws'(or your self-hosted origin). Note there is no trailing slash:e.originis a bare origin, so a comparison against'https://three.ws/'never matches.Listen for
messageevents onwindow, not on the iframe element itself:window.addEventListener('message', (e) => { if (e.origin !== 'https://three.ws') return; console.log(e.data); });Use the correct envelope shape. There are three related protocols, and none uses a type prefix like
3dagent::- The agent iframe bridge (
/agent/<id>/embed) uses{ type: 'agent:*', agentId, ... }: send{ type: 'agent:hello', agentId }first, wait foragent:ready, then drive it with{ type: 'agent:action', agentId, action: { type: 'speak', text: '...' } }. Every message must carry theagentId. See example 9 in the Examples gallery. - The element bridge (
src/embed-host-bridge.js) wraps every message in{ v: 1, source: 'agent-host' | 'agent-3d', id, kind, op, payload }, e.g. a speak request is{ v: 1, source: 'agent-host', id: '<uuid>', kind: 'request', op: 'speak', payload: { text: '...' } }. - The host protocol (specs/EMBED_HOST_PROTOCOL.md) uses
{ v: 1, type: 'host.*' | 'embed.*', id, payload }, e.g.{ v: 1, type: 'host.chat.message', payload: { ... } }.
Messages that don't match the expected envelope (missing
agentIdorv: 1, wrongsource/type) are silently ignored.- The agent iframe bridge (
For element embeds, use the
EmbedHostBridgeclass (src/embed-host-bridge.js) rather than rawpostMessage: it handles the handshake, queues requests until the iframe is ready, and correlates responses byid.
Floating agent hidden behind other elements
Symptom: mode="floating" agent is clipped or hidden behind page content.
Fix steps:
- The element sets
z-index: 2147483000internally via:host([mode="floating"]). If another element has a higher z-index, it will cover the agent. - Check parent elements for
overflow: hidden: this can clip absolutely-positioned children even with a high z-index. - If the agent is inside a stacking context (e.g. a
position: relativecontainer withz-index), the z-index is relative to that context. Move<agent-3d>to a direct child of<body>if possible.
Agent looks tiny or invisible on mobile
Symptom: The agent element exists in the DOM but renders as a 0×0 or very small box.
Likely cause: No explicit dimensions set. The web component has no intrinsic size.
Fix steps:
- Set explicit dimensions. A good mobile starting point:
<agent-3d style="width: 100%; height: 50vh;" ...></agent-3d> - Avoid
display: inlineon the container: useblockorflex. - For inline mode with automatic aspect ratio, set the
widthattribute and omitheight. Responsive sizing is on by default, so there is noresponsiveattribute to add:
The element then sets<agent-3d mode="inline" width="320" ...></agent-3d>aspect-ratio: 3/4and height follows width. Two things switch it off: an explicitheightattribute, andresponsive="false". A CSS-only width (style="width:100%") does not engage it, because the element reads thewidthattribute, not the computed style.
4. Authentication Issues
Can't connect wallet
Symptom: "Connect Wallet" button does nothing or shows an error.
Fix steps:
- MetaMask: confirm the extension is installed, unlocked, and the correct account is selected.
- WalletConnect: QR codes expire after ~60 seconds. Refresh the page and try again.
- Confirm you're on the correct network. Some operations require switching to Base (chain ID 8453) or Base Sepolia (chain ID 84532 for testnet).
- Incognito / private mode: MetaMask may not inject
window.ethereumin private windows. Try a normal window.
"invalid_domain" error during wallet sign-in
Symptom: After signing the SIWE message, the server returns a 400 invalid_domain error.
Likely cause: The PUBLIC_APP_ORIGIN environment variable doesn't match the domain in the browser URL bar.
Fix steps:
- Set
PUBLIC_APP_ORIGINto exactly the origin users are hitting (e.g.https://www.yourdomain.com).www.yourdomain.comandyourdomain.comare treated as different domains. In production this lives on the Cloud Run service (gcloud run services update three-ws-api --region us-central1 --update-env-vars PUBLIC_APP_ORIGIN=...). - For local development, any
localhostdomain is accepted automatically, you don't need to setPUBLIC_APP_ORIGINfor local dev. - For forks deployed on Vercel, the deployment host injected as
VERCEL_URLis automatically trusted alongsidePUBLIC_APP_ORIGIN.
Session expires unexpectedly
Symptom: Users are logged out before the 30-day session window.
Likely cause: JWT_SECRET changed between deploys, which invalidates all existing sessions.
Fix steps:
- Set
JWT_SECRETonce and don't rotate it unless needed. In production it lives in Secret Manager, referenced by the Cloud Run service (node scripts/read-service-env.mjs '^JWT_SECRET$' --rawto read it), and it must be the same value across all revisions. - Session duration is 30 days. A session used when fewer than 7 days remain is rotated to a fresh 30-day token (a rolling refresh window), so actively returning users stay signed in indefinitely.
API key authentication fails
Symptom: Requests using an API key return 401 or 403.
Fix steps:
- The key must be sent as
Authorization: Bearer <key>, include theBearerprefix with a space. - Check if the key has been revoked in the dashboard (Settings → API Keys).
- Verify the key's scope includes the endpoint you're calling. For example, reading avatar data requires
avatars:read; creating or updating requiresavatars:write.
5. Blockchain / ERC-8004 Issues
Transaction reverts during registration
Symptom: The on-chain registration transaction fails with a revert error.
Fix steps:
- Increase the gas limit by 20%: registration involves IPFS CID storage and can exceed estimates.
- Check your ETH balance on Base. Bridge more if needed.
- Verify the manifest CID resolves on IPFS before calling the contract. A CID that doesn't resolve yet may cause the contract to reject it depending on the registry version.
- Confirm MetaMask is on the chain you intend to register on. The platform default is Base (chain ID 8453). The registry contracts are deployed at the same addresses on all major EVM chains, but your wallet must be on the chain the registration flow targets, with gas funds on that chain.
"IPFS pinning failed" during registration
Symptom: The upload step fails with a pinning error before the transaction is even sent.
Fix steps:
- Retry: IPFS providers go down occasionally. Wait a minute and try again.
- Check
PINATA_JWT(or your configured IPFS provider key) in your environment variables. - The default backend uses R2 storage (via
/api/erc8004/pin). If you're supplying a Pinata JWT directly to the client, verify the token is valid and not expired in the Pinata dashboard.
Agent doesn't appear on the discover/explore page after registration
Symptom: Transaction confirmed but the agent isn't visible on the on-chain listing.
Fix steps:
- Wait 1-2 minutes. The indexer polls the chain periodically.
- Access the agent directly by URL:
https://three.ws/a/<chainId>/<agentId>, this bypasses the index. - Confirm the transaction was actually confirmed (not just submitted) on the block explorer for Base.
ENS resolution not working
Symptom: Looking up an agent by ENS name returns "not found".
How it works: the API resolves the ENS name to its address, then returns the agents registered to that wallet address. There is no ENS text record to configure: the match is on the address your name resolves to.
Fix steps:
- Verify the ENS name resolves to the wallet address that owns (or is linked to) your agent. If the agent's registered wallet is a different address than the one your ENS name points to, the lookup returns nothing.
- ENS record changes can take 30+ minutes to propagate after being set.
- Test direct resolution against the API:
https://three.ws/api/agents/ens/yourname.eth(public, rate-limited; returns the resolved address and matching agents as JSON).
6. Memory Issues
Agent forgets everything on reload
Symptom: The agent starts fresh with no memory of previous conversations.
Likely causes:
- Memory mode is
"none": conversations are never persisted - localStorage was cleared
Fix steps:
- Check the
memoryattribute or manifest setting. The default mode is"local"(persisted tolocalStorage). If your manifest or element setsmemory="none", memory is intentionally disabled. - Verify
localStorageisn't being cleared. Open DevTools → Application → Local Storage and look for keys of the formagent:<agentId>:memory. If they're missing after a conversation, check if your browser settings clear storage on close. - Private/incognito mode:
localStorageis cleared when the window closes. This is browser behavior, not a bug.
IPFS memory not loading on another device
Symptom: A user's memory is stored but doesn't appear when they sign in on a different device.
Cause: The IPFS CID pointer is stored in localStorage, which doesn't sync between devices.
Fix: Cross-device memory sync is not implemented in the current release. It requires a server-side memory backend. Stay tuned for an upcoming release that adds this. For now, each device maintains its own local memory.
7. Performance Issues
Model loads slowly
Symptom: The model takes many seconds to appear, or shows a long loading spinner.
Fix steps:
- Check file size. Over 10 MB is noticeable on mobile; over 50 MB is slow on most connections.
- Enable Draco compression on export. In Blender's glTF exporter: Geometry → Compression → enable. This typically reduces mesh data by 5-10×.
- Scale down textures. 4096×4096 textures are rarely necessary, 1024×1024 is fine for most avatars. Use KTX2 format for GPU-compressed textures that decompress on the GPU rather than in JavaScript.
- Merge meshes in Blender before exporting. Fewer objects = fewer draw calls = faster load.
Low FPS / choppy animation
Symptom: Frame rate is visibly low or the animation stutters.
Fix steps:
- Open the stats panel (visible in the dat.gui panel on the right side of the viewer). Check which metric is the bottleneck, GPU time or JavaScript time.
- Reduce polygon count. Under 100k triangles renders at 60fps on most desktop GPUs; under 50k for mobile.
- Disable environment maps on mobile: IBL (image-based lighting) is GPU-expensive. Set
preset="none"or use a simple directional light preset. - Limit the number of
<agent-3d>elements on a single page. Each one creates a WebGL context. Most browsers cap WebGL contexts at 8-16; 4-6 is a safe limit, fewer on mobile.
Page freezes when loading a large model
Symptom: The browser UI freezes for several seconds while the model loads.
Cause: GLB parsing runs on the main thread. Models over ~50 MB can cause noticeable jank.
Fix steps:
- Compress with Draco: the WASM decoder is more efficient and has less UI thread impact than uncompressed mesh parsing.
- Split the model into multiple smaller files if possible, and load non-essential parts after the main avatar appears.
- Moving model loading to a Web Worker is technically possible but requires custom viewer configuration, advanced use case.
8. Self-Hosting Issues
"Cannot connect to database" on startup
Symptom: Server throws on startup or API routes return 500 with a database connection error.
Fix steps:
- Verify
DATABASE_URLis set. The format for Neon is:postgres://user:password@host/dbname?sslmode=require. - If using Neon: check that your server's IP is in the Neon project's IP allowlist (or set it to allow all IPs during development).
- Run the full schema bootstrap to ensure every table exists:
npm run db:bootstrap
relation "…" does not exist errors in production logs
Symptom: API routes and crons throw NeonDbError: relation "agent_custody_events" does not exist (or forge_creations, x_triggers, club_tips, unstoppable_activity, …). Often hundreds or thousands of identical errors.
Cause: The database was provisioned with only part of the schema, typically apply-schema.mjs was run but the incremental migrations under api/_lib/migrations/ were not. The base schema does not create migration-defined tables.
Fix: Point DATABASE_URL at the affected database and run the complete bootstrap. It is idempotent, it only creates what is missing:
DATABASE_URL=<prod connection string> npm run db:bootstrap
Run npm run db:status first to preview which migrations are pending.
API routes return 500
Symptom: Requests to /api/* return HTTP 500 with no useful body.
Fix steps:
- Check the server logs. Production runs on Google Cloud Run (service
three-ws-api, regionus-central1); read recent errors with:
Deploys ship viagcloud logging read 'resource.type="cloud_run_revision" resource.labels.service_name="three-ws-api" severity>=ERROR' \ --freshness=1h --limit 20 --format="value(textPayload)"npm run deploy:gcp(runnpm run buildfirst for frontend changes), the full runbook lives in the repo atdocs/ops/gcp-production.md. On a self-hosted fork, check whatever your host surfaces as function/process logs. - The most common cause is a missing environment variable. All required vars must be set:
DATABASE_URL,JWT_SECRET,PUBLIC_APP_ORIGIN. Theenv.jsmodule throws on startup if required vars are absent. In production, read them withnode scripts/read-service-env.mjs '^DATABASE_URL$|^JWT_SECRET$|^PUBLIC_APP_ORIGIN$' --names(credentials are Secret Manager references, sodescribealone shows no value) and set a non-secret one withgcloud run services update three-ws-api --region us-central1 --update-env-vars KEY=value. A credential goes in Secret Manager instead: seedocs/ops/wallet-key-migration.md.
PWA / service worker serves stale assets after deploy
Symptom: After deploying a new version, some users still see the old UI.
Fix steps:
- Hard-refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac).
- Clear the service worker manually: DevTools → Application → Service Workers → "Unregister", then DevTools → Application → Clear Storage → "Clear site data".
- Service workers cache aggressively and can serve stale content for up to 24 hours. This is expected behavior, users will update automatically when the SW checks for a new version.
Augmented Reality (AR)
The AR button doesn't appear on mobile
Symptom: The <agent-3d ar> element renders correctly, but no AR button is visible on an iPhone or Android phone.
Check 1: ar attribute is present:
<agent-3d id="..." ar></agent-3d>
Without ar, the button is never rendered, even on supported devices.
Check 2: correct browser:
- iPhone: must be Safari. Chrome, Firefox, and all other iOS browsers use WebKit but lack the Quick Look integration that triggers AR. The button is hidden for non-Safari iOS browsers.
- Android: must be Chrome (or a Chromium-based browser with ARCore). Firefox on Android does not support Scene Viewer or WebXR AR.
Check 3: inside an iframe:
Add allow="xr-spatial-tracking" to the <iframe> element. Without it, the browser blocks navigator.xr inside the frame.
<iframe
src="https://three.ws/embed/avatar/YOUR_ID"
allow="microphone; camera; xr-spatial-tracking; fullscreen"
></iframe>
Check 4: model not yet loaded: The AR button is only shown after the GLB finishes loading. If the model is large or on a slow connection, the button appears late. Check the console for load errors.
Check 5: HTTP origin:
navigator.xr is undefined on http:// origins. All AR methods require HTTPS for the page or the model URL. Use an ngrok tunnel or a deployed HTTPS environment during development.
AR button appears but tapping it does nothing
iOS: The model URL is http://. Quick Look silently refuses non-HTTPS model URLs, it opens briefly then closes immediately, or never opens. Use an HTTPS URL for both the page and the GLB.
Android: ARCore is not installed. Chrome shows a "Get ARCore" prompt on first use; if dismissed, nothing happens. Direct the user to install ARCore from the Play Store, then try again.
WebXR fallback: The page origin is http://. navigator.xr.isSessionSupported throws on insecure origins.
Quick Look opens but immediately closes
Almost always a model problem:
- File too large. Quick Look on older devices struggles above ~15 MB. Compress textures and simplify geometry, see model optimization.
- Draco-compressed GLB. Quick Look doesn't include a Draco decoder, the file may load partially then fail. Decompress it:
npx @gltf-transform/cli optimize model.glb out.glb --no-draco. - CORS missing on the model URL. Quick Look fetches the file separately from the browser, and CORS failures are silent. Verify
Access-Control-Allow-Origin: *is present on the response headers for the GLB URL. - USDZ conversion failed. Check the browser console for errors before Quick Look opens, the in-browser USDZExporter logs any failures. A corrupt or oversize USDZ causes immediate dismissal.
The model is invisible or floating in WebXR
Background not cleared: Verify the scene background is null when the XR session starts. If it's opaque, it occludes the camera passthrough, the agent is there but hidden behind the background color.
Agent placed off-screen: If activateAR() is called before the agent is positioned in the viewport, the model may be anchored outside the camera frustum. Ensure the agent is visible in the standard 3D view before activating AR.
Hit-test not resolving: WebXR hit-test requires a real flat surface with texture. Blank white desks, uniform floors, and glass surfaces confuse ARCore. Try a surface with visible pattern or grain.
USDZ conversion is slow or fails
The in-browser GLB → USDZ conversion runs in the main thread and can take 5-15 seconds for complex models. If it fails:
- Check the browser console for errors from
USDZExporter. - Try the model in the glTF Validator first, invalid GLBs often cause export failures.
- Skinned/rigged meshes export as static poses in USDZ (animations are lost, this is expected).
- Models over ~30 MB may time out or exhaust memory during conversion on mobile. Reduce the model size before attempting Quick Look.
Pre-generate USDZ files on the server and set ios-src to skip in-browser conversion entirely.
Testing AR locally (HTTPS required)
All three AR methods require HTTPS. navigator.xr is undefined on insecure origins; Quick Look and Scene Viewer require the model URL to be HTTPS regardless of the page origin.
Option 1: ngrok:
npm run dev # starts dev server on port 3000
ngrok http 3000 # creates an HTTPS tunnel
# Open the ngrok URL on your phone
Option 2: a deployed HTTPS environment:
Deploy your change and test against the live HTTPS URL. There are no per-branch preview deployments in the production flow, three.ws production deploys with npm run deploy:gcp to Cloud Run. A fork hosted on Vercel or Netlify does get an HTTPS URL per deploy, which works the same way for AR testing.
Chrome WebXR emulator (desktop testing): Chrome 127+ includes a WebXR device simulator under DevTools → More Tools → WebXR. It won't show camera passthrough but lets you test the session lifecycle and model placement logic without a physical device.
See the AR & WebXR guide for the full platform compatibility matrix and programmatic API reference.
FAQ
Is three.ws free?
The core platform is free. API usage costs (Anthropic for LLM, ElevenLabs for TTS) are charged at cost, you supply your own API keys. IPFS pinning for on-chain registration requires a Pinata JWT or uses the default R2 backend.
Can I use any 3D model, or does it have to be a humanoid?
Any glTF 2.0 / GLB model works. Humanoid models with the correct skeleton and morph targets unlock the full emotion system (facial expressions, head movement). Non-humanoid models display and animate fine, they just won't show emotions.
Does the agent work without an Anthropic API key?
The 3D viewer, animations, and widget system all work without a key. The LLM conversation feature requires setting the brain attribute on the element and a valid API key. If no key is configured, the element uses NullProvider (no-op), it won't respond to chat messages.
Can I self-host without Vercel?
Yes: production itself doesn't run on Vercel. Since 2026-07-07, three.ws production is a single container on Google Cloud Run: server/index.mjs serves the static frontend and every api/** handler, and reads vercel.json's route table at runtime as its routing config. That server is the reference implementation for self-hosting on any Node.js host. If you'd rather use your own routing layer (Express routes, Nginx proxy_pass, etc.), replicate the vercel.json rewrite rules there, the API routes are standard Node.js async functions. Deploying a fork to Vercel also still works.
Is the agent data private?
In local memory mode, all conversation memory stays in the browser's localStorage. Conversation messages are sent to the Anthropic API (subject to Anthropic's privacy policy). Model files are never uploaded unless you explicitly save to your account. If you're building a sensitive application, review what data flows through each API.
The IdleAnimation (blink / head-drift) doesn't seem to work.
Idle blink and head-drift are active in the current release: src/idle-animation.js is wired into src/agent-avatar.js (instantiated on avatar load and ticked every frame). If you don't see blinking, the usual cause is the model itself: the blink layer needs the eyeBlinkLeft / eyeBlinkRight morph targets, and head-drift needs a Head or Neck bone. Check the Console for the avatar module's missing-morph-target warning, and see "Agent emotions not showing" above for the full morph-target list.