Troubleshooting and recovery

Copy the editable source before changing anything in the environment. Most failures are easier to reproduce than to rebuild after browser storage or local files are gone.

Glyphfield Design Lab with live shader, canvas, layers, and output inspector visible — Inspect the whole rendering chainSource → preview → export

Glyphfield Animation timeline and motion preview — Motion has additional checkpointsFrames → encoder → downloaded file

First steps

Stop playback and any export in progress.
Copy the current source from the source drawer (the Code button), or with readSource() in the Browser API (window.glyphfield.studio).
Write down the active identity, the public tool ID, the output settings and the exact error.
Keep the original local files available.
Retry only after changing the condition that caused the failure.

Do not clear site data, delete a project or rebuild the document from an example as a first step.

Symptoms

Symptom	Likely cause	Next step
Switching tools or projects keeps the previous pane on screen for a moment	The next editor is still loading. The Studio keeps the previous pane visible until the new one is ready	Wait for the new pane. The first switch to a tool loads its code, and later switches are faster
The source drawer takes a moment the first time it opens	The source editor loads when a drawer opens for the first time	Wait for the drawer. Later drawers open without the delay
A shader canvas is blank, grey or static	No WebGL2 (a grey placeholder labelled "Shader preview unavailable"), a lost WebGL context, or the preview is offscreen	Scroll the preview into view, close duplicate live canvases, reload once and try another material. A static fallback is not evidence of motion
A Shaders.com material shows a still with "WebGPU is unavailable here", or an Effect layer passes its layers through unchanged	The browser has no WebGPU	Use a browser with WebGPU. An export that includes these layers stops with an error that names the layer. Hide the layer to export without it
Live shaders look soft	Live shader preview quality is Draft, or Auto lowered it after slow frames	Choose High, or wait: Auto returns to High after a run of smooth frames. Exports always render at the output size
The canvas looks clipped or too small	The view's zoom or pan differs from the output geometry	Use Fit canvas or Reset view and check the declared output size. Zoom does not change the export size
Logos, text or layers shift after a restore	Rebuilt or stale source, changed IDs, missing assets or fonts, or the wrong tool	Apply the exact current document, keep IDs and order, restore the missing files and read the source again after applying
The save status shows Preparing assets for a long time, or Autosave failed	IndexedDB is blocked or full, a write failed, or the page closed during a write	Copy the source from the source drawer right away, stay on the same origin and retry in a normal browser profile
An image import says "Browser storage is full"	Embedded brand images have filled this origin's storage quota	In the image or sticker picker, delete unused saved assets and confirm, then retry. Layers already on an artboard keep their embedded copy
A local image or font disappears after a reload	The file was held in a temporary object URL and was not embedded	Attach the authorized original file again and export a new portable source and proof
A PNG or JPG is empty	The canvas context or the encoder returned no bytes	Try a smaller size to diagnose it, reload the renderer and require a non-empty Blob
A GIF has a flashing text or color frame	The source color changes between frames, or the palette cannot hold the intended colors	Compare stills at the same times, confirm the source colors are stable, use a solid background where it fits and retry at a smaller test size
A GIF jumps where it loops	The GIF repeats, but its last frame differs from its first	In Design Lab, choose Blended loop and inspect the loop point. In Animation, end on the first scene's pose. Use Raw motion only for motion that already repeats or for an intended cut
MP4 export fails with "This browser cannot encode an MP4 video."	The browser exposes no MP4 video encoder	Keep the source and use another supported browser. Glyphfield does not substitute GIF
MP4 export fails with "This browser cannot encode an MP4 audio track."	The Animation timeline has audio and the browser cannot encode it	Remove the audio to test the video alone, or use a browser that encodes MP4 audio
An export stalls or memory use spikes	Several jobs at once, or too many pixels times frames	Stop other previews, run one export, test a smaller width, frame rate or duration, then return to the required settings
`applySource()` throws	A JSON, schema or field validation error, the wrong active tool, or a stale API handle	Read `describe()` and `readSource()` again, change only the intended field, and wait for `glyphfield:studio-api-ready` after switching tools
The docs sidebar misbehaves at a narrow width	Stale CSS or client state, or an embedded webview	Reload, try the same page in a current full browser and include the viewport size in the report

Design Lab, Animation, Lottie and the expression tools autosave the complete portable document to IndexedDB. A small localStorage recovery journal holds the newest source while a write is still in progress.

Return to the exact origin and browser profile where the design was edited.
Reload once without clearing any data.
Select the original identity and tool.
Wait for the save status to show Autosaved, or Saved when a named design is open.
Open the source drawer and copy the restored document.
Inspect the design, then select Save checkpoint and export a proof.

If the design does not return, check whether the hostname, scheme, port, browser profile or private-browsing state changed. Browser storage does not follow those changes.

Diagnose source application

const studio = window.glyphfield.studio;

console.log({
  tool: studio.activeTool(),
  description: studio.describe(),
  controls: studio.controls(),
});

const before = studio.readSource();

try {
  const document = JSON.parse(before);
  // Make one targeted change and keep the envelope and stable IDs.
  await studio.applySource(document);
  const after = studio.readSource();
  if (!after) throw new Error('The applied source could not be read back.');
} catch (error) {
  console.error(error);
  // Keep `before`, and do not write to browser storage directly.
}

After switching projects or tools, wait for glyphfield:studio-api-ready and read window.glyphfield.studio again. A cached handle rejects source and control calls once its editor is no longer active, so get a new handle instead of retrying the old one.

Diagnose a still export

For PNG and JPG:

Export at a modest width such as 960 pixels.
Confirm that the returned Blob is not empty.
Confirm that the MIME type and the file extension match.
Decode the file and check its pixel dimensions.
Check transparency in a PNG and the opaque background in a JPG.
Compare the result with the preview at Fit canvas or at 100% zoom.

If the small export succeeds and the full size fails, the cause is most likely memory or GPU pressure. The source itself is valid.

Diagnose a GIF

Inspect more than the first frame. A valid GIF can contain no visible motion.
Compare the text and logo colors in several frames to tell source flicker from palette limits.
Keep important foreground colors explicit. Glyphfield reserves palette entries for known brand and text colors, but a complex moving palette can still need a smaller test or a simpler composition.
Use Blended loop only when the loop must close, and inspect the change from the last frame to the first.
GIF has no audio channel.

Diagnose an MP4

The MP4 encoder looks for a video codec the browser can encode, trying H.264 first, and fails before rendering when none is available. When the Animation timeline has audio, the export also needs an MP4 audio codec.

Change one thing at a time:

Run one export job only.
Lower the width.
Lower the frame rate or the duration.
Remove the audio to test the video alone.
Use a current desktop browser with hardware acceleration.

Restore the requested size and audio once the cause is found. A lower-resolution test file is not the deliverable unless the requester accepts it.

Information for a report

Collect this information without including confidential assets:

The Glyphfield URL and the deployed commit or version, if known.
The browser and operating system.
The viewport size and device pixel ratio.
The active identity and public tool ID.
The source schema versions (the full source is not needed).
The material ID, output format, dimensions, duration, FPS, quality and loop mode.
Whether Canvas 2D, WebGL2, WebGPU, IndexedDB, localStorage and downloads work.
The exact error message and whether a non-empty Blob was returned.
A screenshot or short recording of the failure.

For API errors, include the HTTP status, error.code, error.field and the request kind, and remove embedded assets.

Browser support, Backup and restore, Errors and limits and Version compatibility cover related problems.