Troubleshooting Guide

The image returns 404

A 404 indicates that the requested path does not match a file in the published collection. Check the asset type, quality, ID and casing first.

• Emoji SVG: /emojis/svg/1f632.svg
• Emoji PNG: /emojis/72x72/1f632.png
• Flag SVG: /flag/l/IN.svg
• Flag icon: /flags/4x3/in.svg

Use the corresponding asset explorer to confirm the actual filename.

The helper is undefined

If window.SoftHoursDiary is undefined, the browser bundle may not have loaded or the URL may be incorrect.

<script defer src="https://softhoursdiary-emojis.pages.dev/soft-hours-diary.js"></script>
<script defer src="/assets/app.js"></script>

Deferred scripts execute in document order. If you load the helper dynamically, wait for its load event before calling methods.

Unsupported quality value

Quality names are case-normalised by the helper. Use one of the values above instead of inventing a size label.

Flag filename has the wrong case

The two flag collections use different casing. The legacy flag SVG collection uses uppercase codes. The flag icon collection uses lowercase codes. The helper normalises this for you, but manually constructed URLs must use the right case.

Emoji Unicode ID is confusing

Use a lowercase hexadecimal code point, for example 1f632. Multi-code-point sequences join the hex values with hyphens. The helper can also accept a literal Unicode character and convert it to hexadecimal.

SoftHoursDiary.emojiUrl("1f632");

// Literal Unicode is normalised to code points.
SoftHoursDiary.emojiUrl("😳");

CORS or fetch errors

Ordinary image display through img does not need JavaScript access to the response. If your code uses fetch(), canvas pixel access or a library that reads a cross-origin response, inspect the request origin and CORS response headers.

The CDN allowlist currently names the Soft Hours Diary website origin. See CORS & crawlers for the details.

Next.js next/image rejects the host

Add softhoursdiary-emojis.pages.dev to images.remotePatterns in next.config.ts and restart the development server. A plain img element does not need this Next.js host allowlist.

npm install cannot find the package

Playground preview is missing

The playground generates a URL locally and then asks the browser to fetch that image. A valid URL can still point to a missing file. Check the asset ID in the explorer and inspect the browser network panel for the HTTP status.