--- layout: default title: Troubleshooting description: >- Fix common problems with the Ink Story Template: story not loading, images not showing, saves not working, itch.io upload issues, and browser errors. --- # Troubleshooting Solutions to common problems. If your issue isn't here, [open an issue on GitHub](https://github.com/RemyVim/ink-if-story-template/issues) or use the [bug report form](https://forms.gle/a6HKbMZ7AhXV8kGu9). For general questions, see the [FAQ](faq.md). {% include toc-closed.html %} --- ## Story Won't Load ### "Story Loading Error" appears The template shows this error screen when it can't load or parse your story. The error message usually tells you what's wrong. **"story.json not found"** - The file must be named exactly `story.json` (not `Story.json`, `story.jason` or `story.JSON`) - It must be in the root template folder, same level as `index.html` - Make sure you exported from Inky, not just saved the `.ink` file **"Failed to load story" or JSON parse errors** - Re-export from Inky: File > Export to JSON - Check Inky for errors first: if Inky shows red text, fix those before exporting - Open `story.json` in a text editor and check it's not empty or truncated ### Blank page / nothing appears This is different from the error screen—you see nothing at all. **Check the browser console.** Right-click > Inspect > Console tab. Red error messages will point to the problem. **Common causes:** 1. **You're opening `index.html` directly.** Double-clicking the file won't work. Browsers block local files for security. Upload to a host or use a [local server](guides/local-testing.md). 2. **Missing template files.** Make sure `js/template.min.js` and `css/template.min.css` exist and aren't empty. 3. **Modified `index.html` incorrectly.** If you edited the HTML file, you may have broken script or link tags. ### Story loads but looks wrong (no styling) The CSS file isn't loading. - Check that `css/template.min.css` exists and is not empty - Check the browser console for 404 errors (Right-click > Inspect > Network tab) - If you moved files around, paths in `index.html` might be broken --- ## Inky / Export Problems ### Inky shows errors and won't export Red text in Inky's console panel (bottom right) means syntax errors. Common mistakes: - **Missing `-> END` or `-> DONE`**: every path needs to terminate - **Forgetting to indent after choices**: text after `*` or `+` must be indented - **Mismatched brackets**: every `{` needs a `}` - **Referencing knots that don't exist**: check spelling of `-> knotName` diverts - **Using `//` in URLs**: Ink treats `//` as comments, omit `https://` from links Fix all errors (red) before exporting. Warnings (orange) usually won't prevent export. ### "Export to JSON" is grayed out Your story has errors. Check Inky's console panel and fix them. ### Exported JSON is huge / tiny - **Huge (several MB):** Normal for long stories. Ink's JSON is verbose. - **Tiny (under 1KB):** Something's wrong. Your story is empty or Inky exported an error state. Check for errors. --- ## Tags Not Working ### Images, audio, or formatting don't appear / appear literally as # TAG Tags are processed by the template, not Ink—you won't see effects in Inky's preview. - Run your story in a browser to see tags in action. See [local testing](guides/local-testing.md) for ways to preview your story in your browser. - Make sure the tag exists and is not misspelled: - Check the [Quick Reference](quick-reference.md) for a list of all supported tags - Tone indicator tags must be defined before use with `# TONE: tagname icon` - Check the console (Right-click > Inspect > Console) for warnings about invalid tags ### Tag syntax reminders - Tags are case-insensitive: `# IMAGE:`, `# image:`, `# Image:` all work - Tags are space-insensitive: `# IMAGE:`, `#IMAGE:`, `#IMAGE :` all work - File paths are relative to the template folder - Use forward slashes on all platforms: `assets/image.png` ### "Unknown tag" warning in console - Check spelling—the console should suggest similar valid tags - For custom CSS classes, use `# CLASS: yourclass` - For tone indicators, define them first: `# TONE: tagname icon` --- ## Images Not Showing Tags are processed by the template, not Ink—you won't see images in Inky's preview. See [local testing](guides/local-testing.md) for options to preview in your browser. ### Image appears broken / missing 1. **Check the filename exactly.** Case matters on most servers: `Image.jpg` ≠ `image.jpg` 2. **Check the file location.** Images typically go in `assets/`: ```ink # IMAGE: assets/myimage.jpg ``` 3. **Check the file format.** Supported: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg` 4. **Check the browser console** for 404 errors showing the exact path being requested. (Right-click > Inspect > Network) ### Image shows locally but not online File paths are case-sensitive on web servers but not on Windows. If your file is `MyImage.JPG` but your tag says `# IMAGE: assets/myimage.jpg`, it works locally but breaks online. **Fix:** Rename files to lowercase and match exactly in your Ink tags. Make sure you use forward slashes in the tag file path. ### Image is too big / too small Use the size parameter: ```ink # IMAGE: assets/photo.jpg 50% # IMAGE: assets/icon.png 100px ``` See [Images reference](reference/images.md) for all options. ### Background image persists after restart This is expected—background images persist across restarts. Use `# BACKGROUND: none` to remove it explicitly. --- ## Audio Not Playing Tags are processed by the template, not Ink—you won't hear audio in Inky's preview. See [local testing](guides/local-testing.md) for options to preview in your browser. ### No sound at all 1. **Check the Settings menu**: is audio enabled? 2. **Browser autoplay policies**: browsers block audio until the user interacts with the page. Audio works after the first click/choice. 3. **Check the file exists**: same troubleshooting as images. 4. **Check the format**: use `.mp3` for maximum compatibility. 5. **Check the browser console** for audio errors. (Right-click > Inspect > Console) ### Audio loops unexpectedly (or doesn't loop) - `# AUDIO: file.mp3`: plays once - `# AUDIOLOOP: file.mp3`: loops continuously To stop looping audio: `# AUDIOLOOP: none` See [Audio reference](reference/audio.md). ### Audio plays locally but not online File paths are case-sensitive on web servers but not on Windows. If your file is `MyAudio.MP3` but your tag says `# AUDIO: assets/myaudio.mp3`, it works locally but breaks online. **Fix:** Rename files to lowercase and match exactly in your Ink tags. Make sure you use forward slashes in the tag file path. --- ## Saves Not Working ### Saves disappear between sessions Saves use the browser's localStorage. They can be lost if: 1. **Reader clears browser data** 2. **Private/incognito mode**: localStorage is wiped when the window closes 3. **URL changed**: localStorage is tied to the exact domain/path 4. **Storage is full**: rare, but possible Encourage readers to use **Export Save** for important progress. ### "Save appears corrupted" error The save data doesn't match the expected format. Causes: 1. **Story structure changed significantly**: renamed knots, changed variables 2. **Browser storage corruption**: rare **For readers:** Start a new game, or try importing a previously exported save file. **For authors:** Warn readers that old saves might not work after major updates. ### Save slots show wrong story title Each save stores the title at save time. If you changed `# TITLE:`, old saves show the old title. They still work—it's just cosmetic. --- ## Functions Not Working Functions added by the template are processed by the template, not Ink—you won't see their effects in Inky's preview. See the list of supported [functions](reference/functions.md) and [debug functions](reference/template-control.md#debug-functions). See [local testing](guides/local-testing.md) for options to preview in your browser. ### "Missing function binding" error - Declare the function with `EXTERNAL` at the top of your `.ink` file - Spelling must match exactly (functions are case-sensitive and use uppercase) - Make sure `template.min.js` loads before your story runs ### Function returns unexpected value - `REPLACE` only replaces the first occurrence: use `REPLACE_ALL` for all - `PERCENT` returns a rounded integer, not a decimal - Time functions return Unix timestamps: use `FORMAT_DATE` to display them ### Date showing wrong format Pass a valid locale string: `"en-US"`, `"fr-FR"`, etc. Invalid locales fall back to `"en-US"`. Check the console for warnings (Right-click > Inspect > Console). --- ## Template Controls Not Working Control tags and debug functions (`DEBUG_LOG`, `DEBUG_WARN`) are processed by the template, not Ink—you may not see their effects in Inky's preview. See the [Template Control reference](reference/template-control.md). See [local testing](guides/local-testing.md) for options to preview in your browser. ### Content keeps accumulating / screen won't clear You're in continuous display mode (the default). To clear on each choice: ```ink # AUTOCLEAR: on ``` Or use `# CLEAR` for a one-time clear at specific moments. ### CLEAR doesn't clear the screen - The tag must be on its own line: `# CLEAR` - Check for typos (tags are case-insensitive, so `# clear` works too) ### RESTART doesn't work - `# RESTART` shows a confirmation dialog: the reader must confirm - Check the browser console for errors (F12 > Console) ### Debug output not appearing 1. **Open the browser console**: F12 (or Ctrl+Shift+I), then click "Console" 2. **Check declarations**: Make sure you added `EXTERNAL DEBUG_LOG(message)` and `EXTERNAL DEBUG_WARN(message)` at the top of your `.ink` file 3. **Check spelling**: Function names must be exact—`DEBUG_LOG` not `debug_log` 4. **Test in browser**: Debug functions don't work in Inky's preview 4. **Check filters**: Check that info and warning level logs aren't filtered in the browser console ### "Missing function binding" for DEBUG_LOG/DEBUG_WARN Same fix as other functions: - Declare with `EXTERNAL` at the top of your `.ink` file - Spelling must match exactly (uppercase) - Make sure `template.min.js` loads before your story runs --- ## Stat Bars Not Showing Tags are processed by the template, not Ink—you won't see stat bars in Inky's preview. See [local testing](guides/local-testing.md) for options to preview in your browser. - The variable must be declared with `VAR` before using it - Variable names are case-sensitive - Check the console for warnings (Right-click > Inspect > Console). --- ## Special Pages Not Appearing Special pages are processed by the template, not Ink—you won't see them in Inky's preview. See [local testing](guides/local-testing.md) for options to preview in your browser. ### Page not in menu - Tag must be on the line immediately after the knot: `# SPECIAL_PAGE` or `# SPECIAL_PAGE: Name` - Always end special pages with `-> DONE` ### Wrong order in menu - Default order is alphabetical by display name - Use `# PAGE_MENU: knot1, knot2, knot3` for custom order - Use `,,` to add separators See [Special Pages reference](reference/special-pages.md). --- ## Choices Issues ### Tone indicator showing wrong icon - Define tones at the top of your file: `# TONE: tagname icon` - For Material Icons: `# TONE: danger warning` - For emoji: `# TONE: flirty 🔥` ### Tone tag not applying to choice Tags must be inside or before the brackets: ```ink // ✓ Works + [Some choice # flirty] + # flirty [Some choice] // ✗ Doesn't work (tag applies to result text, but since it's // no longer a choice at that point, it won't appear at all) + [Some choice] # flirty ``` ### Choice number hints not showing - Check Settings > Choice Number Hints - If you set `# CHOICE_NUMBERS: off`, hints are disabled - Hints auto-hide on touch devices by default --- ## Keyboard Shortcuts Not Working - Check Settings > Enable Keyboard Shortcuts - Shortcuts are disabled when typing in input fields - Shortcuts are disabled when modals are open - Shortcuts are automatically disabled on mobile --- ## Styling Problems ### `custom.css` changes don't appear 1. **Hard refresh**: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac) 2. **Check file location**: `custom.css` should be in `css/` 3. **Check syntax**: validate at [jigsaw.w3.org/css-validator](https://jigsaw.w3.org/css-validator/) 4. **Check specificity**: try adding `!important` temporarily to test if your styles are being overridden ### Dark/light mode doesn't change after customizing The template has separate variables for each theme. If you only customized one, the other might not change. See [Styling reference](reference/styling.md). --- ## Mobile Problems ### Text is tiny on mobile Check that `index.html` has the viewport meta tag: ```html ``` ### Can't scroll on mobile Check for `overflow: hidden` in your `custom.css`. --- ## Local Testing Issues ### Double-clicking `index.html` doesn't work Browsers block local files for security. You need a local server to preview on your computer: see [Local Testing](guides/local-testing.md). ### Changes don't appear after editing - Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac) - Make sure you re-exported to JSON after modifying your `.ink` file - Check you're editing the correct file --- ## Browser Console Errors This template will show error and warning information in the browser's console. Check it with Right-click > Inspect > Console (or F12 > Console). ### "inkjs is not defined" or "Story is not defined" JavaScript files aren't loading. Check that `js/template.min.js` exists and the browser console's Network tab for failed requests (Right-click > Inspect > Network). ### "Cannot read property 'X' of undefined" Usually means the story didn't load correctly. Check for earlier errors in the console and fix those first. ### CORS errors "Blocked by CORS policy" means you're testing locally by opening `index.html` directly. Use [a local server](guides/local-testing.md) instead. --- ## itch.io Problems ### "No compatible uploads were found" You didn't check "This file will be played in the browser." 1. Go to your project > Edit 2. Find your uploaded zip 3. Check "This file will be played in the browser" 4. Save ### Game shows but is tiny / has scroll bars Configure embed settings: 1. Edit your project on itch.io 2. Scroll to "Embed options" 3. Set dimensions (800×600 is reasonable) 4. Check "Mobile friendly" 5. Save and test Alternatively for the best experience, tick the full screen option in the Embed options. ### Game loads but shows the demo story You didn't replace `story.json` before zipping. 1. Delete the existing `story.json` in your template folder 2. Copy YOUR exported `story.json` into the folder 3. Re-zip and upload ### Zip file structure is wrong itch.io needs `index.html` at the root of the zip, not inside a subfolder. **Wrong:** ``` my-game.zip └── my-game/ ├── index.html └── ... ``` **Right:** ``` my-game.zip ├── index.html ├── story.json └── ... ``` **Fix:** Open your folder, select all the files *inside*, then zip those. Don't zip the folder itself. --- ## Still Stuck? 1. **Check the browser console.** Right-click > Inspect > Console. (Or F12 > Console.) Errors usually point to the problem. 2. **Test with the demo story.** Download a fresh template and test without modifications. If the demo works, the problem is in your story or customizations. 3. **Search existing issues.** [GitHub Issues](https://github.com/RemyVim/ink-if-story-template/issues?q=is%3Aissue) 4. **File a bug report**: [Open an issue on GitHub](https://github.com/RemyVim/ink-if-story-template/issues) or use the [bug report form](https://forms.gle/a6HKbMZ7AhXV8kGu9)