Troubleshooting

If your issue is not listed, check the material’s detail page specs and account entitlements. Support volume stays low when licensing and install are clear — include your material slug, framework, and a minimal repro.

Hydration mismatches

WebGL and browser-only APIs must not run during SSR in a way that diverges from the first client paint. Frameline materials wait for mount before attaching the live renderer and show the static fallback until then.

• Do not gate the whole page on typeof window without a matching server output — use a client shell with a static first paint.
• Avoid reading localStorage or media queries during render for colors; prefer CSS variables that resolve identically on server and client.
• If you see “Text content does not match” around a material, confirm you are not rendering random seeds or Date in the label tree.

// Good: static on server + first paint, live after mount
const mounted = useHasMounted()
return mounted ? <LiveShader /> : <StaticFallback />

WebGL fails or never starts

• Confirm the browser supports WebGL and that hardware acceleration is enabled. Corporate policies sometimes disable it.
• Check the console for context-lost events. Recover by remounting or staying on the static fallback.
• Multiple canvases competing for GPU memory will fail on mid-tier devices — keep one active material in view (performance guide).
• Pass forceStatic in constrained environments rather than showing a broken canvas.

Theme colors look wrong

• Verify props receive var(--token), not resolved hex from a build-time theme helper that only runs on one side.
• Confirm the dark-mode class (or data attribute) is on an ancestor when you expect dark tokens.
• Override fallbackColors when you customize — otherwise reduced-motion and pre-mount states show the Frameline demo palette.
• Full pattern: Theming & tokens.

Install returns 403

Registry 403 means the request was understood but not authorized for that package.

• Free SKUs should not require a token. If a free install 403s, check you are hitting @frameline/… and not a mistyped paid slug.
• Paid SKUs need FRAMELINE_REGISTRY_TOKEN in the environment the CLI sees (shell env or .env.local loaded by your tooling).
• Confirm the plan covers the material — Personal vs Team scopes differ; revoked refunds invalidate tokens.
• Regenerate the token from /account if it was rotated or leaked.

Install walkthrough: Installation. Rights questions: Licensing.