Troubleshooting
Common integration issues when embedding the rooomAvatars Editor and using the API.
Are you an LLM? You can read better optimized documentation at /docs/rooom-avatars/troubleshooting.md for this page in Markdown format
This guide covers common issues when embedding the editor iframe, authenticating API requests, and handling errors during avatar registration and export.
Editor does not load
Check that:
- The iframe
srcincludes#token=YOUR_API_TOKENin the URL hash. - The editor host URL is correct and reachable.
- The
allow="camera"attribute is set on the iframe (required for the image-to-avatar feature; not needed for the standard editor flow).
Unauthorized (HTTP 401)
POST /avatar returns 401 Unauthorized when the bearer token is missing or incorrect.
CORS or forbidden origin (HTTP 403)
The API can be configured to accept requests only from a single origin (API_ALLOWED_ORIGIN). If you see 403 Forbidden, verify that API_ALLOWED_ORIGIN matches the origin of your embedding page.
Model generation fails
If GET /model/:id.glb returns a JSON error, the avatar model could not be generated. Check the API server logs for details.