Troubleshooting¶
Start with the diagnostics task, which checks the JDK, Android SDK, plugins, KSP and credentials and suggests a fix for each problem:
./gradlew :app:storeDump prints the resolved configuration and the full render matrix.
Setup¶
No screenshots are found
- Check that KSP is applied in the module (
id("com.google.devtools.ksp")) and that the functions are top-level,@Composable, parameterless and notprivate. - The KSP manifest is written to
build/generated/ksp/<variant>/resources/META-INF/store-studio/. - In multi-module projects, apply the plugin to the module that contains the screenshots.
The KSP plugin isn't found
Chameleon Store Studio applies KSP for you only if the KSP plugin is on the build classpath. Declare it in
the root build with apply false (see Installation).
Duplicate screenshot id
Ids must be unique in a module and across merged modules. The error names both source files.
Rendering¶
Preview host 'ComposeViewAdapter' is missing
androidx.compose.ui:ui-tooling must be on the rendered variant's classpath. It's added to
debugImplementation automatically; add it yourself if you render another variant or disabled
autoDependencies.
A screen renders with Robolectric instead of Layoutlib
The validation report has an ASSET_RENDER_FALLBACK_USED finding with the Layoutlib error. Typical
causes are code that reads databases, files, BuildConfig from another module or native libraries
while composing. Pass sample state instead.
A screenshot fails in both engines
The task fails with the root exception from the renderer log. The logs are in
build/store/render/work/ and build/store/render/robolectric-work/.
Rendering stalls, times out or runs out of memory
Store Studio fails the task with an explanation, and such renders are never cached. Raise
rendering.rendererJvmArgs (-Xmx3g), lower batchSize or maxParallelProcesses, and check free
disk space.
Text in another language doesn't appear
Each locale renders with your localized resources. Make sure the translation exists in
values-<lang> (Android) or composeResources/values-<lang> (Compose Multiplatform), and that the
locale is registered in storeStudio { locales { } }.
Validation¶
Validation fails in a library module
Library modules only run per-image rules. If listing rules run, the module is being treated as
an application; make sure it applies com.android.library or the Android KMP library plugin.
I can't lower the severity of a rule
Hard store requirements can't go below ERROR, because the store would reject the upload. See the
hard rules in Validation.
Baselines and CI¶
Images drift between my machine and CI
Rendering can differ by a few pixels between operating systems. Compare renders from the same
machine: in CI, render the base branch on the runner (-PstoreStudio.diff.renderBase=true) instead
of verifying a baseline recorded on a laptop. If you must mix platforms, use PERCEPTUAL.
Git repository is shallow
--against needs the ref in your clone. Use fetch-depth: 0 in actions/checkout.
Rendering the base revision fails
The base build runs in a temporary worktree; its full log is in
build/store/diff/base-render/base-render.log, and the last lines are shown in the error. If the base
revision doesn't apply Store Studio yet, every image is reported as added.
The pull request comment isn't posted
Pass --post-pr-comment (a flag, without =true), give the token pull-requests: write, and check that the job runs on
a pull_request event (the PR number is read from it) or pass --pr-number.
IDE plugin¶
The tool window is empty
It reads build/store/ of each module. Run ./gradlew storeExport and click Refresh.
Double-click doesn't open the source
Navigation needs the Kotlin plugin and an indexed project. Wait for indexing to finish.