Documentation

Troubleshooting & FAQ

What you'll learn

Common validation findings and how to fix them, frequent questions, and current limits.

Validation findings

The validation badge (app) and vitrine validate (CLI) report findings per target and language as error, warning or info. Errors make vitrine validate exit with 1; --strict fails on warnings too. The most common ones:

CodeLevelMeaning and fix
screenshot_missingerrorno screenshot with this key in the language or its fallbacks – a placeholder is shown. Add the file, or use Preview mode / --preview while designing.
screenshot_fallbackinfothe screenshot comes from a fallback language – fine.
screenshot_aspectwarning (note)the capture’s aspect differs from the device display – wrong device or wrong screenshot variant folder? Up to 5 % with Fit: Cover it is only a note: a thin edge is cropped, e.g. iPhone screenshots on the Android frame of a Google Play target. Fine to keep; for an exact fit add Android screenshots in screenshots/<lang>/android-phone/.
screenshot_upscalewarningthe capture is enlarged more than 15 % and may look soft – use a capture from a larger device.
text_overflowerrorthe text doesn’t fit even at its minimum size – see Fitting long texts.
emergency_breakwarninga word was broken without a hyphen – add a soft hyphen \-.
hyphenatedinfothe text was hyphenated automatically – check the render.
text_fallbackwarning / infotext from the default language (“not translated”, warning) or from another fallback (info).
text_missingerrorthe key exists in no language – nothing is drawn.
text_in_gap, text_clippedwarningtext reaches into a store gap or past its page and is cut off.
text_outside_safe_areawarningtext outside the target’s safe area.
low_contrastwarningthe text’s contrast against what is actually drawn behind it (colour, gradient, photo, pattern) is below WCAG AA – 4.5:1, large text (from 80 lu, bold from 62 lu) 3:1. The message names the ratio, where, and what lies there (an element, or the text’s own shadow/glow/outline, which counts as backdrop); change the colour, add a scrim, shadow or outline.
text_near_devicewarning / infoglyphs hidden behind or running over a device frame (warning), or closer than 16 lu to it (info). Text lying completely on a device, or on a card over it, is fine.
screen_header_covered, screen_header_cutinfoan element covers the top bar (status bar, app title) of a device’s screen, or a page/image edge or the device’s clip cuts through it so half a bar shows (the message names the edge).
screen_coveredinfoan element drawn over a device covers 15 % or more of its screen below the top bar – the app content the screenshot is there to show.
device_cutinfothe left or right page edge (Clip: Home page) or the outer canvas edge cuts more than 8 lu off a device – typically the corners of a tilted device. Top and bottom crops are not reported.
seam_overlapinfoan element reaching across a page border is drawn over an element of the next page – check the gallery.
seam_splitinfoone shape built as two halves at a page border: the store gap pulls them apart. Use one element with Clip: none across the border – it stays continuous behind the gap in every target.
element_in_cornerinfoan element reaches into an image corner the store rounds off (parts hidden under an opaque element above don’t count).
device_smallinfothe largest device of a page fills less than half of it.
page_not_coveredinfoa picture or panel covers almost the whole page but leaves a thin strip (typical after a variant changed the page height).
page_blends_with_storeinfothe edges of the images are hardly distinguishable from the store’s light or dark background.
missing_glyphswarningcharacters no font can draw – add a fallback font.
variant_suggestedinfothe target’s page aspect differs a lot from the canvas – consider a variant.
store_size, store_count, store_formaterrorthe size, number of images or format is not accepted by the store slot (too few images is a warning).
required_store_set_missingwarningthe project goes to a store but lacks something that store requires. App Store: the iPhone 6.3″ set (ios-iphone-63), the iPad 13″ set (ios-ipad-13, only once the project has iPad targets) or the Mac set. Google Play: phone screenshots (play-phone) or the feature graphic (play-feature-graphic, a banner). Add the target from that preset. Export and upload still work; the store won’t submit or publish without it.
imported_frame_missinginfoApple bezels or a frame pack aren’t installed here – the built-in frame is drawn.
imported_frame_not_storedinfoa target draws Apple bezels only this computer has – CI would draw the built-in frame; store them in the project.
stored_frames_staleinfobezels stored in the project are no longer used, or this computer has a newer import – update the stored frames.
imported_frames_storedinfothe project stores Apple bezels – keep the repository private.
color_profile_unsupportedinfoan image’s colour profile can’t be used (CMYK, HDR) – it is drawn as sRGB.
background_hiddenwarninga canvas background layer lies under an opaque one and never shows – canvas backgrounds are layers, not one per page (see below).

In the app, Show on the canvas jumps to the element.

The design checks (low_contrast to page_blends_with_store) render the images; vitrine validate --no-pixel-checks skips them. When a design means it – giant clipped type, a label pointing at a device – list the code in the element’s allow (allow: [text_clipped, low_contrast], also on a group). Project-wide thresholds and codes switched off go into project.yaml:

checks:
  device_distance: 16      # lu between glyphs and a device frame
  min_contrast: 4.5
  min_contrast_large: 3
  screen_cover: 0.15       # share of a screen an element may cover
  off: [page_blends_with_store]

page_blends_with_store, variant_suggested and required_store_set_missing belong to no element, so allow can’t silence them; switch them off for the whole project with checks.off (e.g. when the required set comes from another project).

Which language is checked. Everything about texts (low_contrast, text_near_device, the text layout findings) and overlaps across page borders that involve a text is checked in every language. The checks about devices, pages and corners run only on the first language of each target (the first of the project’s languages, or of the target’s own language list): screen_header_covered, screen_covered, screen_header_cut, device_cut, device_small, element_in_corner, page_not_covered, seam_split, page_blends_with_store, variant_suggested, seam_overlap between two non-text elements, and the store rules (store_size, store_count, store_format). A German screenshot that changes how a device or a corner looks is therefore not checked by a run over all languages. To check another language, run vitrine validate --lang de, or pick that language in the app – the badge checks the current target and language – and look at its pages.

Questions

Where is the Save button? There is none – every change is saved immediately, as one undo step.

Can I edit the project in a text editor or with Git while the app is open? Yes. Changes on disk are picked up live. If you changed the same thing in the app at the same moment, the app reloads the file and tells you that your last edit was not saved.

My French headline is tiny. Auto-fit shrank it to fit. French often needs noticeably more room than English – “Edit photos in seconds” becomes “Retouchez vos photos en quelques secondes”. Give French a language override with a wider box or a higher minimum size, add a soft hyphen, or switch on hyphenation.

I gave the canvas one background colour per page, but every page has the same colour. The canvas backgrounds are layers over the whole canvas, bottom to top – the top opaque one covers the others. For a colour (or photo) per page add a Background element on each page; it fills its page at every target’s height. Elements paint in the order of their layer (z) and the layers list, so keep page backgrounds at the bottom (a low z).

My background element disappeared behind a photo. Background elements are ordinary layers: an opaque image above them in the layers list (or with a higher z) covers them. Move the background down or give the image transparent areas.

The phone sits too high on Google Play. Google Play’s 1:2 page is shorter than the iPhone page. Set the phone’s Anchor to Bottom, or move it in a variant for the Play target.

How do I get real Apple device frames? Download the Product Bezels from Apple and import them once – see Devices & frames. Importing the .dmg directly fails: open it in Finder, accept the licence, import the mounted volume.

A colleague sees different frames. Apple bezels and app-wide frame packs are stored per computer. Without them, the built-in frame is drawn. Put frame packs you may share into the project’s frames/ folder; Apple’s bezels must be imported by each person.

The export folder has old files. Re-exporting removes images Vitrine Studio wrote earlier and no longer produces, but never other files. Delete foreign files yourself.

Upload says “no editable App Store version”. Create a new version in App Store Connect, then plan again. See Store upload for more messages.

Can I use Vitrine Studio without the app, e.g. in CI? Yes – the CLI validates, exports, imports and uploads; use the standalone CLI archive on build machines and VITRINE_APP_DIR for a separate settings folder. See Automation.

Does Vitrine Studio send data anywhere? Only when you ask it to: store uploads and connection tests go to Apple or Google, the template gallery (in the app or with vitrine gallery) to api.vitrinestudio.app, and the daily update check asks GitHub whether a new version exists (switch it off in App settings → Updates). No statistics, no account.

Can an AI assistant break my project? Every change is one undo step labelled with the assistant’s name, and you see it live. Store uploads need your click. See AI assistants.

Current limits

  • Right-to-left layouts (Arabic, Hebrew) are not mirrored yet.
  • Text inside SVG images is not drawn yet.
  • Exports are sRGB only (no Display P3 output).
  • Gallery gaps of the native store apps are estimates; the store websites were measured.
  • No Swedish hyphenation patterns.
  • Frame packs in frames/ are not recompiled while the project is open – re-open it after changing them.

Getting help

Report bugs and ideas on GitHub. Include the output of vitrine validate --format json if it’s about a project, and never include store keys.

Improve this page on GitHub