Troubleshooting

Invalid or expired embed launch token

Usually means:

• the launch_url is too old
• the iframe was hard reloaded after the launch token expired

What to do:

• mint a fresh session
• use a fresh launch_url

Authentication required

Usually means:

• the iframe has not received meshes:auth yet
• a request happened before auth finished settling
• the token is missing or malformed

What to do:

• confirm the iframe receives meshes:ready
• send meshes:auth only after meshes:ready
• confirm the token is a current session token

Stale-token 401

Usually means:

• the logical session was refreshed
• the iframe is still using an older session token

What to do:

• handle meshes:token-refresh
• refresh the session on your backend
• send the new token with meshes:auth

Iframe appears but no workspace data loads

Check:

• the token was actually sent
• the session workspace matches the intended workspace
• the iframe route is part of the supported embed surface
• the session role is allowed to perform the requested action

Iframe does not resize correctly

Check:

• the host listens for meshes:resize
• the host applies the new height to the iframe
• the host keeps a sensible minimum height

Related docs

• Quickstart
• Iframe Message Contract
• Session Refresh Lifecycle