# Troubleshooting

> Real, current Edit Mode gaps with a workaround for each - material clear, empty folders, KTX2 listing, long asset paths, AVIF decode, and texture compression.

- Source: https://diceytable.com/docs/editor/troubleshooting
- Last verified: 2026-07-27

Every entry here is a real, current gap — not a hypothetical — sourced from
`docs/feature-plans/edit-mode/IMPLEMENTATION-STATUS.md`'s tracked follow-ups and verified against
the current code. Each has a workaround. If something you hit isn't listed here, it may be one of
the [known scripting limitations](https://diceytable.com/docs/reference/known-limitations) instead.

## Clearing a material doesn't visually revert until reload

**Symptom:** you clear a material from an object or a room surface (the Material box's `×`), and
the old look stays on screen instead of reverting to the default board/token/surface appearance.

**Cause:** the runtime's material-apply path only *overrides* the look when a material id
resolves; an empty id is a no-op rather than a revert
(`applyAssignedMaterial`: `if (!materialId) { return; }`).

**Workaround:** reload the scene. The document itself is correct the moment you clear the field —
only the live rendering is stale. See [Assigning and editing
materials](https://diceytable.com/docs/editor/working/materials#common-mistakes) for the full explanation.

## Manually created empty folders disappear on reload

**Symptom:** you use **New ▾ ▸ Folder** in the asset explorer to organize your project tree, and the
empty folder is gone the next time you load the project — even though you didn't delete it.

**Cause:** there's no backend record for a folder — a folder only exists as a path prefix shared
by real assets. A folder with nothing in it yet is client-only UI state.

**Workaround:** move (or upload) at least one asset into the folder before you rely on it
surviving a reload — once an asset's path includes it, the folder is real.

## KTX2 assets are missing from the Textures tab

**Symptom:** a `.ktx2` texture you compressed drags and assigns onto material/surface texture
slots from the asset explorer grid just fine, but it never shows up in the Textures tab's own
list, and its Sampling/WebP panels are unavailable there.

**Cause:** the Textures tab only lists assets that pass `isSupportedTextureContentType` — a
browser-decodable image format. A GPU-compressed KTX2 container isn't one, by definition, so it's
excluded from that list rather than mis-detected.

**Workaround:** find and manage a `.ktx2` asset through the asset explorer grid, not the Textures
tab. Assignment and rendering both work correctly either way. See [Working with
textures](https://diceytable.com/docs/editor/working/textures#the-known-ktx2-explorer-gap).

## Saving fails for a deeply nested or long asset path

**Symptom:** saving an asset you've organized several folders deep fails with no obvious reason.

**Cause:** the move/organize route accepts paths up to 1024 characters, but the shared schema
that persists an asset reference (`modProjectAssetReferenceSchema.path`,
`packages/shared/src/modManifest.ts`) caps a path at **180 characters**. A path that
passes the move but exceeds 180 characters fails at save.

**Workaround:** keep folder nesting and file names reasonably short — a few folders deep with
concise names stays well under the limit. If you hit this, shorten a folder name in the chain
rather than the file name alone, since the whole path counts.

## AVIF images may not decode on every device

**Symptom:** an AVIF image you uploaded previews fine for you but fails to render — or looks
broken — for some players or on some devices.

**Cause:** AVIF upload is accepted, but decode support varies by browser and OS version
(notably older iOS). There's no server-side transcode to fall back to — every peer decodes the
raw file in their own browser.

**Workaround:** prefer **PNG, JPG or WebP** for any texture every peer needs to render correctly
— all three have universal decode support across the browsers DiceyTable targets. Reserve AVIF
for assets you know only you will see (a private reference image), not shared table assets.

## Large-texture compression briefly blocks the editor

**Symptom:** clicking **Compress to Basis** on a 2K+ texture makes the tab visibly freeze for a
moment.

**Cause:** Basis/KTX2 encoding runs synchronously on the main thread — a Web Worker version was
attempted, but the Vite module-worker plus the `ktx2-encoder` dynamic-glue path proved fragile
and was deferred.

**Workaround:** expect a brief pause (worse on larger textures) and don't interact with the tab
until it clears — it's a real compute cost, not a hang. Compressing several large textures back
to back will feel slower than compressing one; there's no batch/background option today.

## See also

- [Known limitations](https://diceytable.com/docs/reference/known-limitations) — the scripting/mod-API equivalent of
  this page
- [Working with textures](https://diceytable.com/docs/editor/working/textures)
- [Assigning and editing materials](https://diceytable.com/docs/editor/working/materials)
- [AI agent troubleshooting](https://diceytable.com/docs/ai-agents/troubleshooting) — pairing, the Local Network prompt,
  keys, screenshots and publish refusals when an AI agent works in the editor
