Skip to main content
This page covers the most common issues users encounter and how to resolve them. If none of these steps solve your problem, open an issue on the Aether GitHub repository with as much detail as possible.
When Aether can’t connect to a provider after saving your key, work through these checks in order:
  1. Re-examine the key itself — open the provider’s dashboard, copy the key again, and paste it freshly. A single extra space at the beginning or end will cause an authentication failure.
  2. Verify the key is active — some providers let you disable or revoke individual keys. Log in to the provider’s dashboard and confirm the key is in an active/enabled state.
  3. Check your account credits or quota — a key can be technically valid but refused if your account balance is zero or your rate limit is exhausted.
  4. Remove and re-add the provider — go to Settings → Model Providers, remove the entry entirely, then tap Add Provider and start fresh.
The first time Aether initializes the Alpine Linux environment, it extracts the runtime assets bundled with the APK. This requires sufficient storage but does not download the rootfs:
  1. Keep Aether open — do not navigate away or kill the app while the setup indicator is visible.
  2. Wait at least 5 minutes — extraction on some devices is slower than expected. Do not navigate away or kill the app while the progress indicator is visible.
  3. Force-stop and retry — if initialization appears completely frozen after 5 minutes, open Android Settings → Apps → Aether → Force Stop, then reopen Aether. It will resume or restart the initialization process automatically.
  4. Free up storage — ensure at least 200 MB of free storage is available on your device. A near-full device can cause the extraction to fail silently.
If Agent Mode cannot operate the isolated virtual display:
  1. Tap the pause button — every active agent session shows a pause/stop control in the composer area. Tap it to interrupt the current run cleanly.
  2. Check Termux setup — open Settings → Termux and confirm command access and external apps are ready.
  3. Check Agent Mode authorization — open Settings → Agent Mode and refresh the selected Shizuku or Root authorization method.
  4. Check your provider’s status page — the hang may be on the provider’s side. Check their status page for ongoing incidents.
If Aether cannot connect to Shizuku for privileged operations:
  1. Confirm Shizuku is running — open the Shizuku app. The main screen should display “Shizuku is running.” If it shows stopped, start it again via Wireless Debugging (ADB).
  2. Grant Aether permission in Shizuku — open the Shizuku app → Authorized apps and make sure Aether appears in the list with permission granted. If it’s absent, the next time Aether tries to use Shizuku it will prompt you to authorize.
  3. Restart Shizuku after a reboot — Shizuku does not persist across device reboots by default. After restarting your phone, open the Shizuku app and start the service again before using Aether’s Shizuku-dependent features.
If the Termux integration is greyed out or not recognized:
  1. Use the correct Termux distribution — you must install Termux from F-Droid or GitHub Releases. The Play Store version of Termux does not support the RUN_COMMAND permission required for integration with other apps.
  2. Verify the permission is granted — use Settings → Termux to open the Android app-permission screen and allow Run commands in Termux environment.
  3. Verify external apps are enabled — run Aether’s setup command in Termux, then return to Aether and refresh.
If Aether repeatedly crashes immediately after launch, a native mod (compiled Kotlin/DEX extension) is likely the culprit:
  1. Restart Aether after the interrupted startup — if startup ended before native-mod initialization and five seconds of UI stability, Aether enters Native Mod Safe Mode on the next launch. In this mode, all native mods are bypassed so the app can start.
  2. Identify the offending extension — once in Safe Mode, go to Settings → Extensions. The extension list will indicate which mod was being loaded at the time of the crash.
  3. Disable or remove the extension — tap the extension entry to disable it or remove it entirely.
  4. Re-enable Native Mods — after removing the problematic extension, tap Re-enable Native Mods in Settings → Extensions. Aether will load the remaining mods normally on the next startup.
If your previous conversations have disappeared:
  1. Check for an uninstall/reinstall — Aether stores chat history in a local database inside its private app storage. Uninstalling and reinstalling Aether permanently deletes all history. There is no recovery path from an uninstall.
  2. Check available device storage — if your device’s storage became completely full while Aether was running, the database may have failed to write new records. Free up space and verify that new messages are saving correctly now.
If your scheduled tasks never run at their appointed time:
  1. Check alarm scheduling — if your Android version exposes Android Settings → Apps → Special app access → Alarms & reminders, allow Aether to schedule exact alarms. Aether falls back to alarm-clock or allow-while-idle scheduling when exact alarms are unavailable.
  2. Disable battery optimization for Aether — go to Android Settings → Battery → Aether → Unrestricted (labeling varies by manufacturer). Without this setting, Android can defer or prevent background wakeups.
  3. Add Aether to your device’s autostart or protected apps list — many OEM Android variants (Xiaomi MIUI/HyperOS, OPPO ColorOS, Samsung One UI, etc.) apply aggressive background process limits beyond the standard Android battery optimization system. Find the “autostart,” “protected apps,” or “background activity” setting in your device’s built-in security or battery app and add Aether to the allowlist.