Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIDeepSeekDeepSeekMuseMuse+22 more

    capacitor android build doctor

    1

    Diagnose and fix Capacitor Android build failures, JDK/Gradle version mismatches, and runtime white-screen issues.

    Free

    Security scanned
    capacitor android build doctor

    capacitor android build doctor

    Example session with this skill installed

    My Capacitor 7 build is failing with "java.lang.UnsupportedClassVersionError: com/android/build/gradle/AppExtension has been compiled by a more recent runtime". How do I fix this?

    • Read your context and instructions
    • Compiled the capacitor android build

    This error indicates a mismatch between your Java Development Kit (JDK) and the Android Gradle Plugin (AGP) version required by Capacitor 7. Specifically, your environment is trying to run a modern AGP with an older version of Java.

    Diagnosis and Fix

    The error "compiled by a more recent runtime" typically means you are using JDK 17 or older, but Capacitor 7's toolchain requires

    JDK 21.

    ComponentRequired Version
    Capacitor Major7
    JDK21
    Gradle Wrapper8.7+
    Android Gradle Plugin8.5.0+

    Recommended Steps

    Check your Java version: Run java -version in your terminal. If it is not 21, install JDK 21 and update your JAVA_HOME environment variable.
    2.

    Update Gradle Wrapper: Open android/gradle/wrapper/gradle-wrapper.properties and ensure distributionUrl points to version 8.7:
    distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
    3.

    Update Android Gradle Plugin: In android/build.gradle, locate the com.android.tools.build:gradle dependency and update it to 8.5.0.
    4. Sync Project: Run npx cap sync android to refresh dependencies.
    5. Rebuild: Run ./gradlew assembleDebug from the android folder.

    Next steps

    • Confirm your IDE (Android Studio) is also set to use JDK 21 in Settings > Build, Execution, Deployment > Build Tools > Gradle.
    • If the build succeeds but the app is blank, check if webDir in capacitor.config.ts matches your actual build output folder.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    If your Capacitor app builds fine for the web but crashes on Android, you are facing a toolchain mismatch. This skill diagnoses Java, Gradle, and Android Gradle Plugin errors to get your APK building again.

    What it does

    • Diagnoses build failures by mapping Gradle logs to specific JDK, Gradle wrapper, and Android Gradle Plugin version requirements.
    • Fixes runtime issues such as the common white screen of death, missing plugin implementations, and local network connection errors.
    • Validates configurations across capacitor.config, Android manifests, and Gradle files to find hidden sync or namespace issues.
    • Guides major upgrades between Capacitor versions 5 through 8 with a step by step migration path for plugins and native dependencies.
    • Prepares release builds by auditing signing configs, target SDK levels, and ProGuard/R8 rules that often break production APKs.

    How it works

    1. Analyze error logs from your terminal or Android Studio to identify the root cause in the toolchain.
    2. Run the build doctor using a local Python script to inspect your android/ folder and project metadata.
    3. Review the version matrix to confirm if your environment matches the specific requirements of your Capacitor major version.
    4. Execute targeted fixes following a prioritized order from toolchain alignment to runtime behavior.

    Frameworks & tools

    Works with Ionic, React, Vue, and Angular projects using Capacitor 5, 6, 7, or 8. Supports Gradle, Android Studio environments, and web build tools like Vite.

    Why this beats prompting it yourself

    Generic LLMs often suggest deleting your android folder, which destroys custom native code. This skill uses a version-aware matrix and a local diagnostic script to find the one line in your Gradle config that is actually broken.

    Use cases

    • Resolve "Unsupported class file major version" or "invalid source release" errors during build.
    • Fix blank screens where the app works in the browser but fails on a physical device.
    • Handle CORS and ERR_CLEARTEXT_NOT_PERMITTED errors when connecting to your API.
    • Transition an existing web project to a functional Android app bundle for Google Play.

    Known limitations

    Does not support iOS builds. Cannot directly execute Android Studio, adb, or Gradle commands. Requires the user to provide logs from their local machine.

    Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Agents & Orchestration.

    iOS is out of scope. Cannot run Android Studio, adb, or Gradle; relies on user-provided logs and file reads. Version matrix covers Capacitor 5-8.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before buying a skill.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Free to use

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 2 days ago

    • Free with an Agensi account

    Software
    capNode.jsvite@capacitor/assets

    Permissions

    Terminal / Shell
    Network Access
    Read Files
    Write Files
    Environment Variables

    Allowed Hosts

    (
    .
    Listed2 days ago

    What's inside

    Frequently Asked Questions

    This skill specifically targets the 'version hell' of Android development, mapping the complex dependencies between the JDK, Gradle, and the Android Gradle Plugin (AGP) to match your specific Capacitor version without deleting your custom native code.

    The Capacitor Android Build Doctor supports all projects using Capacitor versions 5, 6, 7, and 8, whether they are built with Ionic, React, Vue, or Angular.

    No, the skill cannot directly access your terminal or Android Studio; instead, it uses a local diagnostic script to analyze your files and provides specific instructions for you to execute.

    You receive the diagnostic logic, a local Python inspection script, a comprehensive version-compatibility matrix, and step-by-step troubleshooting workflows for both build-time and runtime failures.

    Yes, it provides specific guidance for resolving Android-specific networking issues like 'ERR_CLEARTEXT_NOT_PERMITTED' and local API connection failures that don't appear in web browsers.

    While the skill focuses on the Android platform, it is designed to work within any AI agent environment that supports file analysis and structured diagnostic workflows.

    New in Agents & Orchestration

    Free