Troubleshooting

Most issues fall into a few buckets. This article walks through them; if you're still stuck, open a support ticket with the exact command output.

A project wasn't detected during a scan

Scanning reads real project files. A stack can be missed if its layout is unusual — a monorepo with several package.json files, or a project nested deeper than the scan walked.

• Confirm the signal file exists where expected (.xcodeproj, app/build.gradle, package.json, pubspec.yaml, Cargo.toml).
• Add the lane manually in the project editor and point it at the right toolchain adapter and working directory.
• Watch for the “couldn't confidently detect — confirm” flag in the review table and correct it there.

A build or deploy step failed

• Reproduce on the command line. Run the same build/deploy from a terminal in the lane's working directory. If it fails there too, it's a toolchain or project issue, not AppRelay.
• Check the tool is installed and on PATH — Xcode command line tools, a JDK, Node, a store or hosting CLI.
• Check credentials. A failed upload is often an expired or mis-referenced secret — see Secrets & encryption.
• If the recipe itself is wrong, duplicate it, fix the step, and re-run — see Recipes.

The wrong version was read or written

• Verify the lane's version source points at the correct file and format (for Android, literal vs. derived versionName).
• After a bump, check the file in Source Control before continuing — each format owns its write-back, and confirming the diff catches a bad edit early.
• For unusual formats, switch to a customRegex version source or bump manually.

No simulators or emulators appear

• Device lists come from your installed toolchains. Open Xcode or Android Studio once to install a runtime or create an AVD, then return to AppRelay.
• Confirm the toolchain that provides the device is the one the lane uses.

A .relay archive won't import

• “Wrong passphrase.” The passphrase is case-sensitive and unrecoverable. Re-enter carefully; if it's truly lost, the secrets in that archive can't be decrypted — see Secrets & encryption.
• “Archive is newer than this app.” It was exported by a newer AppRelay. Update the app, then import.
• Repos not found after import. Expected — the archive holds only relative paths. Point AppRelay at the repo root on this machine; see the repo root.

Still stuck?

Open a ticket and include your stack and toolchain, the step that failed, and the exact output. Because AppRelay runs locally with no account, that detail is what lets us help quickly. Please don't paste secrets or passphrases.