Troubleshooting
Use this guide when a build, protected app, CI/CD job, or portal workflow does not behave as expected. Start with the symptom that best matches what you see, collect the build job ID or timestamp, and keep any build logs, API responses, or device details close by.
For tenant-specific investigation, Team and Enterprise tenants can open a support ticket from the AppTego Portal after completing the relevant checks below.
Fast Triage
| Question | Why it matters |
|---|
| Which configuration version was used: Development, Staging, or Production? | The selected version determines which controls, response actions, signing choices, and build settings apply. |
| Which upload path was used: portal, Automation API, GitHub Actions, or CircleCI? | The portal and direct Automation API accept .apk, .aab, and .ipa; the first-party GitHub Actions and CircleCI integrations currently accept Android .apk and iOS .ipa. |
Is the source artifact a valid .apk, .aab, or .ipa for that upload path? | Invalid, damaged, or unsupported archives fail before protection can start. |
| Was the protected app signed for the intended installation path? | QA, enterprise distribution, app stores, and sideloading can require different signing choices. |
| Does the issue reproduce on a physical device? | Runtime controls and platform privacy behavior can differ from emulators and simulators. |
| Did the issue appear after a configuration change? | Build-time controls and many prevention settings require a new protected build before they take effect. |
Build Fails Before Processing
| Symptom | Likely cause | What to check |
|---|
| Upload rejected | Unsupported file type, wrong integration path, or corrupt archive | Confirm the file is valid for the path you used: .apk, .aab, or .ipa for portal/API uploads; .apk or .ipa for the first-party CI/CD integrations. |
429 or quota error | Concurrent build limit or rolling 7-day build quota reached | Wait for in-progress builds to finish, reduce pipeline parallelism, or review plan limits in Subscription and Billing. |
| Immediate failure | Subscription, permission, tenant, or configuration issue | Confirm the tenant, active plan, Builds permission (build_applications), selected configuration version, and that at least one control is enabled for the target platform. |
Build Fails During Processing
| Symptom | Likely cause | What to check |
|---|
| Processing timeout | Very large binary, many native libraries, or slow packaging | Retry once, then contact support with the build job ID or timestamp and source artifact type. |
| Signing failure | Missing or mismatched signing key metadata | Verify keystore alias, passwords, provisioning profile, certificate chain, and selected signing key. |
| Protected app will not install | Signing identity, OS version, architecture, or distribution mismatch | Test on a supported OS version and confirm the build settings match the target device. |
| Build succeeds but output is unexpected | Wrong configuration version, outdated configuration, signing choice, or input artifact | Confirm the uploaded build used the intended Development, Staging, or Production configuration and the expected source artifact. |
CI/CD Authentication Issues
| Symptom | Likely cause | What to check |
|---|
401 from Automation API | Missing, malformed, disabled, unknown, or plan-gated automation key | Recreate or re-enable the key, confirm the tenant is Team or Enterprise, and store the full raw key_id:key_secret value in your CI secret manager. |
| Secret appears blank in CI | Secret name mismatch or missing context | Confirm the workflow input references the same secret or environment variable name configured in your CI provider. |
| Job cannot find artifact | Workspace, artifact path, file extension, or job ordering mismatch | Ensure the mobile build step completes before the AppTego protection step, persists the exact artifact path, and uses the extension supported by that integration. |
| Pipeline times out | Protection needs longer than the job timeout | Increase the CI timeout and the AppTego integration timeout, especially for larger iOS or native-heavy apps. |
Automation API and first-party CI/CD status values are processing, completed, and failed. When available, the progress field contains the current human-readable build stage shown by the portal.
Controls Do Not Behave As Expected
| Symptom | Likely cause | What to check |
|---|
| Control does not trigger | Change was saved after the app was built | Rebuild the app with the intended configuration version. |
| Too many users blocked | Response action is too strict for the rollout stage | Start in Log mode, validate events, then promote stricter responses. |
| Live update not applied | App was not built with live configuration support, or the changed setting requires a rebuild | Rebuild with the required Enterprise setting before relying on live push, and rebuild for build-time or structural changes. |
| Test device triggers detections unexpectedly | Device posture, developer settings, simulator/emulator behavior, or QA tooling is influencing results | Compare against a clean physical device and review dashboard events or Device Logs where available. |
Protected App Behavior
| Symptom | Likely cause | What to check |
|---|
| App launches but immediately exits | A detection response action is configured to terminate | Review enabled detections and test first in Log mode. |
| Sensitive screens cannot be captured | A prevention control is working as configured | Confirm this behavior is expected for the selected configuration version. |
| Network requests fail after protection | Network hardening or pinning policy mismatch | Review connection settings, TLS requirements, and certificate lifecycle. |
| Users see unclear enforcement copy | Default or outdated custom message | Update Custom Messages and validate the message in a non-production environment. |
What To Include In A Support Request
| Detail | Example |
|---|
| Tenant and configuration version | Acme Mobile / Staging |
| Build context | Build job ID or timestamp, app name, platform, file type, upload path, and signing mode |
| Configuration context | Version used for the build and recently changed controls |
| Failure evidence | Error message, sanitized CI log, API response, screenshot, device log, dashboard event, or audit event |
| Reproduction details | Physical device model, OS version, app version, and exact steps |
| Business impact | Release deadline, production impact, or number of affected users |
See Support and Help for support channels, response expectations, and ticket workflow.