Troubleshooting

Most problems have one cause and one fix. Find the message you see.

#In the studio

"This browser can't draw 3D scenes: it has no WebGL." The stage needs WebGL. Open the scene in a desktop browser with hardware acceleration turned on. Editing and saving still work; the last saved cover stands in for the picture. An agent's cloud browser usually has no WebGL: see How agents see.

"The scene is taking a while to draw." The load neither finished nor failed within 20 seconds. Press Try again. If it repeats, the browser has a WebGL context that never draws; use another browser.

"This scene was changed somewhere else. Reload to pick up the latest version." Someone, or an agent, saved a newer revision (REVISION_CONFLICT). Reload the scene, then share. The share dialog’s own version reads “The open scene changed. Open sharing again.”

A blank cover on a tile. The cover was captured by a browser that could not draw. Open the scene in a working browser and save once.

#Importing

"Scene documents must be at most 32 MB." A .puni.json document is capped; asset bytes are separate. Assets inside a portable bundle do not count toward the document, but sampled motion keys can. Export from the studio again, or strip the keys and add motion in the studio.

A GLB imports but shows nothing. Check its size. Very large meshes draw slowly. An asset is capped at 64 MB.

#Command line

PUNI_AUTH. The token is missing, expired, or lacks the render scope. Sign in again with puni auth login --base-url https://puni.design; for the render scope, mint a token with Read, write and render in Settings → Agents instead, because signing in never grants it. Tokens last 30 days.

PUNI_RUNTIME. Your command line is older or newer than the app. Rebuild it from the current checkout.

"Asset storage redirects require an explicit --asset-origin." (PUNI_ASSET_ORIGIN, exit 78.) A scene with uploaded files pulls those files from storage. Pass the storage origin with --asset-origin.

PUNI_CONFLICT, exit 75. The revision you pushed against is stale. Pull, merge your edit, push with the new revision.

#Agents

A 401 from /api/mcp. The token is missing, revoked or expired. Make a new one in Settings → Agents.

"This connection can't edit scenes yet." (HTTP 403 from MCP; the cover route says Missing scope: <scope>.) The token was made read-only. Make a new one with write.

"This result is too large." Ask for a page of objects with inspect_objects instead of the whole scene, or read the document resource in chunks.

Read FAQ and glossary for the words used here.

#Connector stops before consent

If ChatGPT reports Only public clients using PKCE are supported, its client metadata was rejected before consent. This is a Puni compatibility error, not a wrong password. No connection is ready until consent completes and the client can list your scenes. Use a token-based coding client, or report the message with the client name.

If a plugin is mentioned but no Puni tools appear, check its MCP declaration and the host's connection status. A skill alone does not provide tools. Read Connect Puni and Plugins and skills.