Troubleshooting

Start with command exit code. Morphe Builder uses stable categories and keeps integrity failures terminal.

morphe-builder build morphe.toml --keystore /path/to/key.p12 --output build
echo $?

PowerShell exposes the code as $LASTEXITCODE.

Code	Category	First check
2	Configuration	Validate morphe.toml keys and values.
3	Compatibility or availability	Check patch-compatible versions and configured providers.
4	Toolchain	Check Java 21, GitHub access, release assets, and cache integrity.
5	Integrity or identity	Do not bypass. Check package, version, ABI, signer, hashes, and source.
6	Merge	Check split completeness and APKEditor output.
7	Build or signing	Check keystore, password, selected patches, and Morphe output.
8	Module	Check root variant and module packaging inputs.
9	Overwrite refusal	Choose a new output path or deliberately remove old output.

Use --json when automation needs structured final output. Progress and errors remain on stderr.

GOOPDL_ACCOUNT_EMAIL and GOOPDL_AAS_TOKEN must be set together

Only one account variable is configured. Set both or unset both:

export GOOPDL_ACCOUNT_EMAIL='account@example.com'
export GOOPDL_AAS_TOKEN='aas_et/...'

A token starting with g.a is temporary and invalid for this setting. Generate a persistent aas_et/ token using Google Play authentication.

Google Play returns HTTP 403 or 429

Anonymous dispenser access is blocked or rate-limited. Common on CI and datacenter networks.

Preferred fixes:

1. Configure account-backed authentication.
2. Configure APKMirror, Uptodown, archive, or direct fallbacks in morphe.toml.
3. Retry later only when failure is clearly temporary.

Do not convert an integrity failure into provider unavailability. Hash, signer, package, version, and ABI failures must remain terminal.

BadAuthentication

Google rejected password or app-password authentication. Use browser OAuth mode:

morphe-builder aastoken --browser

If no supported browser is detected, set GOOPDL_BROWSER to its executable or use manual morphe-builder aastoken --oauth mode. Changing account password invalidates an existing AAS token. Generate a new token and replace local or GitHub Environment secret values.

No compatible app version

Run:

morphe-builder list-patches morphe.toml

Common causes:

• selected patches have no shared supported version
• exclusive-patches excludes required patches
• Universal or experimental patches were not enabled
• configured patch source or release differs from expected
• exact app version is unavailable from every provider

See configuration version selection and provider fallback.

Java or toolchain failure

Confirm Java 21+ is selected:

java -version

Then retry tool preparation:

morphe-builder tools

A checksum mismatch, unexpected release asset, or invalid provenance is a trust failure. Do not edit cached provenance to force reuse. Remove only the affected public tool cache after confirming no other Morphe Builder process uses it, then download again.

Tool cache location:

• Windows: %LOCALAPPDATA%\morphe-builder\tools
• Linux: $XDG_CACHE_HOME/morphe-builder/tools or ~/.cache/morphe-builder/tools

A stale lock may remain after a crashed process. Remove it only after confirming no process still uses that cache.

Output already exists

Trusted outputs are immutable. Morphe Builder never overwrites them:

refusing to overwrite build output

Choose a new path:

morphe-builder build morphe.toml --keystore /path/to/key.p12 --output build-2

Or inspect and deliberately remove the old directory first. morphe-builder clean does not remove build outputs, trusted downloads, tools, or keystores.

Missing keystore password

build reads password only from MORPHE_KEYSTORE_PASSWORD:

export MORPHE_KEYSTORE_PASSWORD='replace-me'

Passwords are not accepted in command arguments. Confirm environment variable exists in the same shell or CI job that runs build.

Keystore rejected

Check that keystore:

• is a regular file, not a symlink
• exists before build starts
• has matching alias and password
• is PKCS12 or JKS readable by Java 21
• remains outside repository when generated locally

Default alias is morphe-builder. Override it with --keystore-alias when needed.

Never replace a release keystore casually. Different signer makes updates incompatible with installed apps.

Integrity, package, version, ABI, or signer mismatch

Exit code 5 means downloaded or cached content failed trust checks. Do not retry with verification disabled; no such bypass exists by design.

Actions:

1. Keep original error text, after checking it contains no secret.
2. Confirm requested package, version, and architecture.
3. Confirm expected-signer is correct when configured.
4. Re-run verify against existing splits when investigating a cached set.
5. Remove affected trusted cache only after preserving safe provenance needed for diagnosis.
6. Report source URL without query strings, artifact hashes, expected identity, and sanitized error.

A later provider must not override a signer or integrity failure.

Merge or patch failure

Merge failures usually indicate incomplete or incompatible split selection. Patch failures usually indicate patch/tool version incompatibility or invalid option selection.

Run these separately:

morphe-builder list-patches morphe.toml
morphe-builder tools

Review:

• package-specific patch selection
• Universal and experimental patch flags
• scalar patch option names and values
• per-app Morphe CLI and patch source overrides
• source provenance version matching resolved version

Original verified splits remain unchanged. Failed work stays unpublished and disposable.

Clean disposable state

Use built-in cleanup only for intermediate work:

morphe-builder clean

It removes <cache>/work and preserves trusted stock, tools, outputs, and provenance. This is safer than deleting the complete cache when root cause is unknown.

Reporting a bug

Include:

• operating system and architecture
• Python, Java, and Morphe Builder versions
• command with secrets and private paths removed
• exit code
• sanitized stderr
• minimal relevant TOML section
• whether failure reproduces after morphe-builder clean

Never include AAS tokens, cookies, passwords, private keystores, environment dumps, authenticated URLs, downloaded APKs, or private cache contents.