Skip to content

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.

feat(viewer): tell a visitor what to do when the model will not load

nirholas800cc4288fe1
diff --git a/src/avatar-embed.js b/src/avatar-embed.js
index 47fb6ad3e..83b8f7f55 100644
--- a/src/avatar-embed.js
+++ b/src/avatar-embed.js
@@ -73,6 +73,7 @@ import {
} from './runtime/arkit52.js';
import { log } from './shared/log.js';
import { isSafeQueryModelUrl } from './shared/safe-model-url.js';
+import { viewerErrorText } from './shared/viewer-error-text.js';
const BRIDGE_VERSION = '1.0';
const CAPABILITIES = [
@@ -112,28 +113,12 @@ const DEFAULT_HOTKEYS = Object.freeze({
});
main().catch((err) => {
+ // The visitor gets plain language; the raw rejection stays in the console so
+ // a developer debugging an embed still sees which URL and status failed.
+ log.warn('[avatar-embed] load failed', err);
showError(viewerErrorText(err));
});
-// GLTFLoader rejects with the raw transport string, e.g. `fetch for
-// "https://host/x.glb" responded with 502: Bad Gateway`. That names an internal
-// URL and tells the viewer nothing they can act on. Map the failures a visitor
-// can actually hit onto plain language; anything unrecognised keeps its own
-// message, which is already written for a person (resolveAvatar throws
-// "avatar <id> not found").
-function viewerErrorText(err) {
- const msg = String(err?.message || err || '');
- if (/responded with 4\d\d/.test(msg)) {
- return /40[13]/.test(msg)
- ? 'This avatar is private. Sign in with the account that owns it.'
- : 'This avatar is no longer available.';
- }
- if (/responded with 5\d\d/.test(msg)) return 'The avatar service is unavailable. Refresh to try again.';
- if (/Failed to fetch|NetworkError|Load failed/i.test(msg)) return 'Connection lost. Check your network and refresh.';
- if (/glTF|JSON|Unsupported|Unexpected token/i.test(msg)) return "This avatar's 3D file could not be read.";
- return msg || 'Could not load avatar.';
-}
-
async function main() {
const params = new URL(location.href).searchParams;
applyBackground(params.get('bg') || 'transparent');
diff --git a/src/shared/viewer-error-text.js b/src/shared/viewer-error-text.js
new file mode 100644
index 000000000..084c932f5
--- /dev/null
+++ b/src/shared/viewer-error-text.js
@@ -0,0 +1,36 @@
+// GLTFLoader (and three's FileLoader under it) reject with the raw transport
+// string, e.g. `fetch for "https://host/u/abc/model.glb" responded with 502:
+// Bad Gateway`. Shown as-is that names an internal URL, leaks a storage key,
+// and tells the viewer nothing they can act on. Map the failures a visitor can
+// actually reach onto plain language with a next step.
+//
+// Anything unrecognised keeps its own message: the callers that throw by hand
+// already write for a person (avatar-embed's `avatar <id> not found`), so
+// replacing those with a generic string would lose information.
+
+/**
+ * Human, actionable text for a model-load failure.
+ *
+ * @param {unknown} err the rejection from a viewer load
+ * @returns {string} copy safe to show a visitor
+ */
+export function viewerErrorText(err) {
+ // An Error with an empty message must not fall through to String(err),
+ // which yields the useless literal "Error".
+ const msg = (typeof err?.message === 'string' ? err.message : String(err ?? '')).trim();
+ if (/responded with 4\d\d/.test(msg)) {
+ return /\b40[13]\b/.test(msg)
+ ? 'This avatar is private. Sign in with the account that owns it.'
+ : 'This avatar is no longer available.';
+ }
+ if (/responded with 5\d\d/.test(msg)) {
+ return 'The avatar service is unavailable. Refresh to try again.';
+ }
+ if (/failed to fetch|networkerror|load failed|err_/i.test(msg)) {
+ return 'Connection lost. Check your network and refresh.';
+ }
+ if (/gltf|json|unsupported|unexpected token/i.test(msg)) {
+ return "This avatar's 3D file could not be read.";
+ }
+ return msg || 'Could not load avatar.';
+}
diff --git a/tests/src/viewer-error-text.test.js b/tests/src/viewer-error-text.test.js
new file mode 100644
index 000000000..abe46e213
--- /dev/null
+++ b/tests/src/viewer-error-text.test.js
@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { viewerErrorText } from '../../src/shared/viewer-error-text.js';
+
+// The strings on the left are what three's FileLoader actually rejects with
+// (`fetch for "<url>" responded with <status>: <statusText>`), which is what
+// /embed/avatar used to paint straight into its error slot.
+describe('viewerErrorText', () => {
+ it('turns a 5xx transport failure into a retry instruction', () => {
+ const raw = 'fetch for "https://three.ws/api/avatars/abc/glb" responded with 502: Bad Gateway';
+ expect(viewerErrorText(new Error(raw))).toBe(
+ 'The avatar service is unavailable. Refresh to try again.',
+ );
+ });
+
+ it('tells a signed-out visitor which account they need', () => {
+ for (const status of [401, 403]) {
+ const raw = `fetch for "https://three.ws/api/avatars/abc/glb" responded with ${status}: Forbidden`;
+ expect(viewerErrorText(new Error(raw))).toBe(
+ 'This avatar is private. Sign in with the account that owns it.',
+ );
+ }
+ });
+
+ it('reports a missing avatar as gone, not as a permission problem', () => {
+ const raw = 'fetch for "https://three.ws/api/avatars/abc/glb" responded with 404: Not Found';
+ expect(viewerErrorText(new Error(raw))).toBe('This avatar is no longer available.');
+ });
+
+ it('names the network when the request never reached a server', () => {
+ expect(viewerErrorText(new TypeError('Failed to fetch'))).toBe(
+ 'Connection lost. Check your network and refresh.',
+ );
+ });
+
+ it('reports an unreadable model file', () => {
+ expect(viewerErrorText(new Error('Unexpected token < in JSON at position 0'))).toBe(
+ "This avatar's 3D file could not be read.",
+ );
+ });
+
+ it('keeps a message that was already written for a person', () => {
+ const written = 'avatar 00000000-0000-4000-8000-000000000000 not found';
+ expect(viewerErrorText(new Error(written))).toBe(written);
+ });
+
+ it('never returns an empty string', () => {
+ expect(viewerErrorText(undefined)).toBe('Could not load avatar.');
+ expect(viewerErrorText(new Error(''))).toBe('Could not load avatar.');
+ });
+});