[Bug]: Capacitor 9 alpha builds do not support Android 17's new ACCESS_LOCAL_NETWORK permission

[moose4lord]

myApp_sdk36.zip

myApp_sdk37.zip

Capacitor Version

Latest Dependencies:

@capacitor/cli: 8.5.2
@capacitor/core: 8.5.2
@capacitor/android: 8.5.2
@capacitor/ios: 8.5.2

Installed Dependencies:

@capacitor/ios: not installed
@capacitor/cli: 9.0.0-alpha.7
@capacitor/core: 9.0.0-alpha.7
@capacitor/android: 9.0.0-alpha.7

Other API Details

npm version: 11.19.0
node version: v24.20.0
Angular version: 22.1.8
Ionic version: @ionic/angular 9.0.4

Platforms Affected

• iOS
• Android
• Web

Current Behavior

Android 17 (SDK37) introduces a new network permission for accessing devices on the local network, "android.permission.ACCESS_LOCAL_NETWORK". Previously permission to access local network devices used to be granted automatically with "android.permission.INTERNET", but starting in SDK 37 the permission must be granted deliberately. See https://developer.android.com/privacy-and-security/local-network-permission.

Using Capacitor 9 alpha, setting targetSDK=37 and adding the new ACCESS_LOCAL_NETWORK permission to the app AndroidManifest.xml file causes network connections to LAN devices to silently fail.

Expected Behavior

Apparently with SDK 37 you need to add the permission to the manifest file AND add some code to check if the permission has been granted, and if not, pop up a dialog to explicitly ask the user for permission to access the local network.

Project Reproduction

See two attached files. They are Ionic apps which try to make a connection to HTTP servers. myApp_sdk36 uses Capacitor 8 and SDK 36, and seems to work fine, while myApp_sdk37 uses Capacitor 9 alpha and SDK 37 and refuses to make a network connection to devices on the local area network (Internet connections work fine).

Additional Information

I know work on Capacitor 9 is in its early stages, so it's not a big deal yet. I'm just wondering if this is on anyones radar.

[eric-horodyski]

If you could provide a reproduction application demonstrating this it would definitely be helpful for the team! Thanks!!

[fabiomartino]

Hi everyone!
I've investigated and prepared a local fix for the ACCESS_LOCAL_NETWORK permission issue on Android API Level 37+.

I implemented the necessary changes in the core repository (Manifest declaration, PermissionHelper checks with proper backward compatibility for SDK < 37, and Bridge permission validation updates), backed by a new unit test suite.

You can inspect the implementation and branch code here:
https://github.com/fabiomartino/capacitor/tree/feat/ACCESS_LOCAL_NETWORK

Update: ACCESS_LOCAL_NETWORK support implemented in feat/ACCESS_LOCAL_NETWORK

I've implemented baseline support for the API 37+ local-network runtime permission
on top of Release 8.5.2. Design goals: declaring the permission alone isn't
enough on SDK 37+ (runtime request required, otherwise LAN fails silently), and
on SDK < 37 the permission string is unknown to PackageManager, so it must
report GRANTED instead of mis-reporting denied. Since compileSdk is still 36,
everything uses a string literal + raw SDK_INT >= 37 gate (no Manifest.permission
or VERSION_CODES constants exist at compile time).

1. Library manifest — baseline declaration (merged into every app, ignored on older SDKs):

  <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+     <!-- Local-network access on API 37+. Unknown to older SDKs, safely ignored there. -->
+     <uses-permission android:name="android.permission.ACCESS_LOCAL_NETWORK" />
  </manifest>

2. PermissionHelper — constant + version gate (@ since 9.0.0):

+     public static final String ACCESS_LOCAL_NETWORK = "android.permission.ACCESS_LOCAL_NETWORK";
+     public static final int ANDROID_API_LOCAL_NETWORK_PERMISSION = 37;
+     public static boolean isLocalNetworkPermission(String permission) {
+         return ACCESS_LOCAL_NETWORK.equals(permission);
+     }
+     public static boolean isLocalNetworkPermissionEnforced() {
+         return isLocalNetworkPermissionEnforced(Build.VERSION.SDK_INT);
+     }
+     public static boolean isLocalNetworkPermissionEnforced(int sdkInt) {
+         return sdkInt >= ANDROID_API_LOCAL_NETWORK_PERMISSION;
+     }
+     public static boolean isPermissionEnforced(String permission) {
+         return isPermissionEnforced(permission, Build.VERSION.SDK_INT);
+     }
+     public static boolean isPermissionEnforced(String permission, int sdkInt) {
+         if (isLocalNetworkPermission(permission) && !isLocalNetworkPermissionEnforced(sdkInt)) {
+             return false;
+         }
+         return true;
+     }

3. Bridge — version-aware state + validation (pre-37 short-circuits to granted):

  // getPermissionStates(): never touches PackageManager for non-enforced permissions
+                         if (!PermissionHelper.isPermissionEnforced(permString)) {
+                             permissionStatus = PermissionState.GRANTED;
+                         } else if (ActivityCompat.checkSelfPermission(this.getContext(), permString) == PackageManager.PERMISSION_GRANTED) {
  // validatePermissions(): clears stale cache, skips DENIED caching and manifest rejection pre-37
+             if (!PermissionHelper.isPermissionEnforced(permString)) {
+                 // ...clear any cached state...
+                 continue;
+             }
-         String[] permStrings = permissions.keySet().toArray(new String[0]);
-         if (!PermissionHelper.hasDefinedPermissions(getContext(), permStrings)) {
+         // manifest check now built only from enforced permissions
+         if (permStrings.length > 0 && !PermissionHelper.hasDefinedPermissions(getContext(), permStrings)) {

Plugin usage:

@Permission(alias = "localNetwork", strings = { PermissionHelper.ACCESS_LOCAL_NETWORK })

then the standard checkPermissions() / requestPermissions() flow — resolves to
granted without prompting on older devices, full runtime dialog on API 37+.

[moose4lord]

If you could provide a reproduction application demonstrating this it would definitely be helpful for the team! Thanks!!

I added a couple of Ionic test apps which show the issue. They simply make HTTP requests to a web server and display the response.

[fabiomartino]

Hi @moose4lord — I put together a fix for this on feat/ACCESS_LOCAL_NETWORK
in my fork (branch here, based on Release 8.5.2):

• declares android.permission.ACCESS_LOCAL_NETWORK in the core library manifest
  (merged into every app, safely ignored on older SDKs);
• adds a version gate in PermissionHelper (isPermissionEnforced(), string
  literal + raw SDK_INT >= 37 since compileSdk is still 36);
• Bridge.getPermissionStates() / validatePermissions() report GRANTED and
  skip manifest rejection / DENIED caching on pre-37 SDKs, full runtime dialog
  flow on API 37+.

testDebugUnitTest is green (57 tests, 0 failures, incl. 9 new ones covering both
sides of the API-37 gate). No TS changes (PermissionState is generic).

Did you get a chance to try this branch — e.g. running your myApp_sdk37 repro
against it? Curious whether the permission dialog now appears instead of the
silent LAN failure.

And for the maintainers: if there's interest, I'm happy to open a PR upstream —
just waiting for an OK first, so I don't open something that would sit there
unwanted. Thanks!

[moose4lord]

Hi Fabio, thanks for your help with this. I tried to incorporate your fix into my test app, but unfortunately I couldn't figure out how to merge your changes. I tried to use npm to install the code from your GitHub repo, but I just couldn't get it to work. If you can give me some tips on how to integrate you changes into my development environment, I'd be happy to try again.

[fabiomartino]

I built an exportable patch that applies the ACCESS_LOCAL_NETWORK change to the
@capacitor/android package already installed in your project, so you can test the
fix without waiting for a release.

Attached file

capacitor+android+9.0.0-alpha.7+ACCESS_LOCAL_NETWORK.patch capacitor+android+9.0.0-alpha.7+ACCESS_LOCAL_NETWORK.patch

It patches 3 native library files:

• AndroidManifest.xml (declares the new permission)
• PermissionHelper.java (constant + API 37 enforcement gate)
• Bridge.java (treats the permission as granted on SDKs below 37)

How to apply

From your project root (after npm install, so node_modules exists). Your lockfile
must resolve @capacitor/android to exactly 9.0.0-alpha.7, the patch is generated
from that specific package:

git apply capacitor+android+9.0.0-alpha.7+ACCESS_LOCAL_NETWORK.patch

No git? This works too:

patch -p1 < capacitor+android+9.0.0-alpha.7+ACCESS_LOCAL_NETWORK.patch

How to test

1. Open android/ in Android Studio (or run ./gradlew assembleDebug).
2. Install on an API 37 (Android 16) device or emulator and try the local-network
   call. Your config already has server.cleartext: true + androidScheme: 'http',
   so HTTP to the local network is not blocked by the cleartext policy.
   Notes

• npx cap sync android does not touch the library sources, so the patch survives a
  sync. A clean reinstall (npm ci) does remove it, just re-apply.
• To undo: git apply -R capacitor+android+9.0.0-alpha.7+ACCESS_LOCAL_NETWORK.patch

[moose4lord]

Hi Fabio, I tried your patch file, but unfortunately it didn't seem to fix the problem. I could see where the three files you mention changed, so I'm pretty sure the patch was applied properly. But when I run my test app and try to access a local network device, no popup appears asking to grant the ACCESS_LOCAL_NETWORK permission and the HTTP request eventually times out.

I've attached my test app if you want to give it a try.

I'm seeing some weird behavior with Capacitor 9 alpha, so it may be an issue with that release. If I find the time, I'll try to manually applying your patch to the Capacitor 8 files and see if that looks any better.

myApp_fabio.zip

[fabiomartino]

Thanks for zipping the test app — I could look at exactly what happens, and it
confirms the picture: your project already has everything needed (manifest
declaration, targetSdk 37, and the patched core library). The only missing
piece is that nothing in the app code requests the permission at runtime.

On Android, the system dialog only appears when the app explicitly calls
requestPermissions(). The framework patch adds the plumbing so the
permission is tracked and reported correctly, but it cannot — and should not —
trigger the dialog for you: whether to ask the user is an app-level decision.
Flutter and React Native work the same way (the app requests the permission via
a plugin before opening the socket).

In your app the LAN request goes through the native CapacitorHttp plugin (it wraps HttpURLConnection, not OkHttp),
which never requests ACCESS_LOCAL_NETWORK, so the request has to come from the app itself.
The exact change is one file:

android/app/src/main/java/io/ionic/starter/MainActivity.java

package io.ionic.starter;

import android.os.Build;
import android.os.Bundle;
import androidx.core.app.ActivityCompat;
import com.getcapacitor.BridgeActivity;

public class MainActivity extends BridgeActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Android 17 (API 37+) blocks local-network access by default.
        // Trigger the runtime prompt so CapacitorHttp can talk to LAN devices.
        if (Build.VERSION.SDK_INT >= 37) {
            ActivityCompat.requestPermissions(
                this,
                new String[] { "android.permission.ACCESS_LOCAL_NETWORK" },
                1000
            );
        }
    }
}

Then rebuild the Android app (Android Studio, or cd android && ./gradlew assembleDebug), install on the API 37 device/emulator and launch it. The
dialog should appear right at startup — tap Allow — then tap the
HTTP GET button. The request to http://10.0.0.197/status should now
succeed.

⚠️ One warning specific to this permission: ACCESS_LOCAL_NETWORK is one of the
new "limited-denial" permissions — if you deny it twice, the system stops
showing the dialog and treats it as denied until the user changes it in
Settings. So please tap Allow the first time you see it, or the test will
look like it failed.

If you'd rather not touch MainActivity, the production pattern is a small
plugin that declares the permission via @Permission and calls
checkPermissions() / requestPermissions() from JavaScript before the LAN
request — I can post that version too. The MainActivity shortcut is just the
fastest way to confirm the fix works on your device.

And if a maintainer wants to pick this up: the core fix (manifest baseline +
version-aware state reporting/validation in PermissionHelper/Bridge, with
unit tests) is ready as a PR — happy to open it against the right base.

[fabiomartino]

Hi @moose4lord,
Following up on the production pattern I mentioned: since the MainActivity shortcut confirms the fix on your device, here's the plugin version — the one I'd suggest shipping in the core so apps don't need any native code.
The attached capacitor+android+9.0.0-alpha.7+ACCESS_LOCAL_NETWORK.patch
replaces the previous one: the same 3 core files plus a small first-party LocalNetwork plugin (one new native file, LocalNetwork.java) registered in Bridge. No changes to @capacitor/core are needed.
Apply it the same way as before:

npm install                                   # or undo the old one: git apply -R <old-patch>
git apply capacitor+android+9.0.0-alpha.7+ACCESS_LOCAL_NETWORK.patch
npx cap sync android

Then, in your Angular app, two small changes:

1. New file src/app/local-network.ts (local JS proxy for the plugin):

import { registerPlugin } from '@capacitor/core';

export type PermissionState = 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';

export interface LocalNetworkPermissions {
  localNetwork: PermissionState;
}

export interface LocalNetworkPlugin {
  checkPermissions(): Promise<LocalNetworkPermissions>;
  requestPermissions(): Promise<LocalNetworkPermissions>;
}

const LocalNetwork = registerPlugin<LocalNetworkPlugin>('LocalNetwork');

export { LocalNetwork };

2. src/app/home/home.page.ts — import it and request the permission inside getRequest(), right before CapacitorHttp.get():

import { LocalNetwork } from '../local-network';
// ...
const permState = await LocalNetwork.requestPermissions();
if (permState.localNetwork !== 'granted') {
  this.httpStatus = 0;
  this.httpData = 'Local network permission denied. Enable it in app Settings.';
  this.cdr.detectChanges();
  return;
}

Putting the call in getRequest() ties the dialog to your tap on HTTP GET — exactly the user-action model the OS expects. On web and Android < 37 requestPermissions() resolves immediately with granted (no dialog); on Android 37+ the system dialog appears, then the request proceeds.
Same warning as before: ACCESS_LOCAL_NETWORK is a limited-denial permission, so tap Allow — denying twice stops the prompts until it's changed in Settings.
I'm preparing a PR against the next (9.x) branch with the core fix plus this plugin, so the behavior becomes built-in. Let me know how the test goes!

[moose4lord]

Aaah, you're working too quickly ! I can't keep up :)

Thanks for the MainActivity.java patch. I misunderstood what triggered the permission dialog, but your explanation makes sense. I applied the MainActivity.java patch and sure enough the permission dialog appears when the app first launches, and granting the "Nearby devices" permission allows the HTTP GET request to succeed. Woohoo!

Your second solution looks a bit more involved, although you're right, it would be a better user experience if the dialog appeared just before the network connection attempt was made instead of when the app is launched. Would it be better to add your code directly to the CapacitorHttp and avoid the LocalNetwork plugin?

As an aside, another user @ahmetoguzer proposed what looks like a similar solution in the GitHub Discussion area
#8610 (comment).

[fabiomartino]

Hi @moose4lord — 🎉 that's the confirmation we needed! Thanks for being the guinea pig on API 37; a working device test is gold for the PR.

And thanks for the great question — honestly, I'd keep the request out of CapacitorHttp, for three reasons:

1. The permission is app-scoped, not call-scoped. ACCESS_LOCAL_NETWORK is granted once for the whole app. If CapacitorHttp requested it implicitly, the dialog could pop from any code path that happens to hit a LAN address — a background task, a deep link, a retry loop — not necessarily while the user is interacting.

2. A runtime prompt must be tied to user action. That's the model Android expects (and it's what the "limited denial" behavior is built around). Auto-requesting inside the HTTP client would be a silent behavior change for every existing CapacitorHttp app — new dialogs appearing where none existed.

3. Precedent. Flutter and React Native both keep the request explicit: the app asks for local-network access before opening the socket, in its own flow. The framework provides the plumbing; the app decides when to ask — including when to show a rationale.That said, the embedded plugin version gives you exactly the UX you described — dialog right before the network attempt instead of at launch — with zero native code:

const permState = await LocalNetwork.requestPermissions();   // dialog appears here, on first tap
if (permState.localNetwork === 'granted') {
  const response = await CapacitorHttp.get(options);
}

One JavaScript call that both triggers the prompt and gates the request. The plugin itself ships inside @capacitor/android (no separate package to install).

On your aside: yes, great minds think alike 😄 — @ahmetoguzer's point in discussion #8610 (#8610) matches this exactly (it's a regular runtime permission; the app can declare and request it today).

A PR is already open implementing this direction: #8624 (#8624) — ACCESS_LOCAL_NETWORK support + the first-party LocalNetwork plugin, against next, with the unit tests. Which road the maintainers prefer is up to them, but from my personal point of view the embedded-plugin approach is the cleaner long-term solution.

Feedback there is very welcome!