Skip to content

Commit 2741995

Browse files
lyzhang0113lyzhang0113
authored
Update local network access FAQ and screenshots (#979)
* Update local network access FAQ and screenshots * Update last modified date and clarify local network access behavior for Chromium 145+ * Update local network access FAQ with revised content and add LNA permission prompt image * Clarify Local Network Access settings for Chrome 142-144 in troubleshooting guide * update timestamp
1 parent cceb905 commit 2741995

6 files changed

Lines changed: 134 additions & 91 deletions

File tree

‎_articles/faq/chromium-142-local-network-access-issue.md‎

Lines changed: 134 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -7,187 +7,230 @@ keywords: Dynamic Web TWAIN, Error Troubleshooting, CORS, unknown address space,
77
breadcrumbText: Error message - Permission was denied for this request to access the unknown address space
88
description: CORS unknown address space
99
date: 2025-11-04 17:21:42 +0800
10-
last_modified: 2025-12-17 16:00:00 +0800
10+
last_modified: 2026-02-12 10:20:00 -0800
1111
---
1212

1313
# Error Troubleshooting
1414

1515
> [!IMPORTANT]
16-
> This is a newly developing issue, and as such the information in this article may change over time.
16+
> This is an evolving browser behavior. Details in this article may change as Chromium updates Local Network Access.
1717
18-
## Error message - CORS Errors caused by local network access permissions when using Chromium 142 and later
18+
## Error message - CORS errors caused by local network access permissions in Chromium 142 and later
1919

2020
### Overview
2121

22-
Starting in **Chromium-based browsers v142+** (released Oct 28, 2025)—including Chrome, Edge, Brave, and Opera—Dynamsoft Web TWAIN Service may not work as expected due to new **Local Network Access (LNA)** restrictions that limit requests **from public network locations to private and loopback network locations**.
22+
Local Network Access (LNA) is a browser security model that has been enforced in Chromium-based browsers since version 142 (released October 28, 2025), including Chrome, Edge, Brave, and Opera. It blocks web apps from reaching local or loopback targets unless the user explicitly grants permission, which can affect Dynamic Web TWAIN Service behavior.
23+
24+
These restrictions limit requests from **public network locations** to **local or loopback locations** unless the required site permission is granted.
25+
26+
Starting in **Chrome 145**, the site-setting label changed from one permission to two:
27+
28+
- `loopback-network` shown as **Local Network**
29+
- `local-network` shown as **Apps on device**
30+
31+
Dynamic Web TWAIN Service communicates with `localhost` / `127.0.0.1`, so **Local Network** (`loopback-network`) is the key permission for most deployments.
32+
33+
When your page first requests local access, Chromium will show an LNA permission prompt.
34+
This FAQ and the symptoms below apply when users dismiss this prompt or click **Block**.
35+
36+
![LNA prompt](/assets/imgs/local-network-access/LNA-prompt.png)
2337

2438
### Symptoms
2539

26-
You may experience one or more of the following:
40+
If the initial LNA prompt is dismissed or blocked, you may experience one or more of the following:
2741

2842
#### **1) Browser repeatedly prompts to download the service**
29-
The browser asks the user to download/install the Dynamsoft Web TWAIN Service even though it is already installed.
43+
The browser asks the user to download/install the Dynamic Web TWAIN Service even though it is already installed.
3044

3145
![DWT_installer.png](/assets/imgs/DWT_installer.png)
3246

3347
#### **2) Initialization succeeds, but scanning / loading returns blank**
3448
Initialization appears successful, but scanned or loaded images are blank.
3549

36-
The browser console (F12 → Console) may show a CORS denial similar to:
50+
The browser console (`F12` -> `Console`) may show a CORS denial similar to:
3751

3852
```shell
3953
Access to fetch at 'https://127.0.0.1:18623/fa/VersionInfo?ts=1761893667670'
4054
from origin 'https://your-domain.com' has been blocked by CORS policy:
4155
Permission was denied for this request to access the `unknown` address space.
4256
```
4357

44-
This error occurs because the web page is loaded from a public network origin (for example, `https://your-domain.com`) and is attempting to connect to a loopback network location (`127.0.0.1`), which Chrome now treats as a protected local network request.
58+
This happens because a page on a public origin (for example, `https://your-domain.com`) is trying to access a loopback address (`127.0.0.1`), which Chromium now treats as a protected local-network request.
4559

4660
---
4761

4862
#### Version-Specific Behavior
4963

50-
The observed behavior depends on Chromium browser version and Dynamic Web TWAIN (DWT) version:
64+
Observed behavior depends on Chromium version and Dynamic Web TWAIN (DWT) version:
5165

52-
| Browser Version | DWT Version | Resulting Symptom |
53-
|-------------------|------------------|-----------------------------|
54-
| Chromium 142 | < 18.5.0 | Download Prompt |
55-
| Chromium 142 | ≥ 18.5.0 | Blank Images after Scanning |
56-
| Chromium 145+ (*) | Any | Download Prompt |
66+
| Browser Version | DWT Version | Resulting Symptom |
67+
|------------------|-------------|-----------------------------|
68+
| Chromium 142-144 | < 18.5.0 | Download Prompt |
69+
| Chromium 142-144 | >= 18.5.0 | Blank Images after Scanning |
70+
| Chromium 145+ (*) | Any | Download Prompt |
5771

58-
> (*) **Chromium 145, which can also block websocket, has not been officially released.**
59-
> Behavior is based on pre-release testing and may change once the final release becomes available.
60-
> Edge 143 and Firefox Nightly will have local network permission control as well.
72+
> [!NOTE]
73+
> (*) Blocking WebSocket requests is on Chromium's roadmap, and may be enforced in a future release.
74+
> Other browsers are also introducing local network permission controls.
6175
6276
### Root Cause
6377

64-
Chromium 142 introduces and enforces a new [Local Network Access (LNA)](https://chromestatus.com/feature/5152728072060928) security model that restricts requests **from public network locations to private and loopback network locations**, requiring explicit user permission.
78+
Chromium 142 introduced [Local Network Access (LNA)](https://chromestatus.com/feature/5152728072060928), which restricts requests from public network locations to local/loopback network locations unless permission is granted.
6579

6680
> [!NOTE]
67-
> For background and design rationale, see Chrome’s Developer Blog: [New permission prompt for Local Network Access](https://developer.chrome.com/blog/local-network-access).
81+
> For background and design rationale, see Chrome's developer blog: [New permission prompt for Local Network Access](https://developer.chrome.com/blog/local-network-access).
6882
69-
Under this model, **requests originating from a public network location** (such as a publicly hosted website) **to private or loopback network locations** (including localhost and 127.0.0.1) are blocked by default unless the user explicitly grants permission.
83+
Under this model, requests from a public origin (a publicly hosted site) to local or loopback targets (including `localhost` and `127.0.0.1`) can be blocked by default.
7084

71-
Dynamic Web TWAIN relies on a locally installed service that listens on a loopback address. When a web application hosted on a public domain attempts to communicate with this service, Chrome categorizes the request as a **public-to-local** network request, which now requires explicit user consent.
85+
Dynamic Web TWAIN relies on a locally installed service that listens on a loopback address. If browser permission is not granted, communication with that local service fails.
7286

7387
### Resolution
7488

7589
> [!WARNING]
76-
> The steps outlined below **do not “fix” or bypass this restriction**, nor can Dynamic Web TWAIN override it programmatically. They simply ensure that the browser’s required permission is correctly granted so the local Dynamic Web TWAIN service is allowed to communicate with your application.
90+
> This is driven by browser security policy decisions. Dynamic Web TWAIN cannot bypass these restrictions programmatically.
91+
> Browser behavior will continue evolving, and temporary workarounds may be removed in future versions. You should plan your deployment and UX flow around current browser permission requirements.
7792
78-
***1. To Manually Correct This in Chrome***
93+
***1. To manually correct this in Chrome***
7994

8095
- Navigate to your Dynamic Web TWAIN page.
8196
- Click the lock/settings icon in the browser address bar.
82-
- Ensure that **Local Network Access** is enabled.
97+
- In **Chrome 142-144**, ensure **Local Network Access** (`local-network-access`) is `Allow`.
98+
- In **Chrome 145+**, check:
99+
- **Local Network** (`loopback-network`) is `Allow` (required for `localhost` / `127.0.0.1`)
100+
- **Apps on device** (`local-network`) is `Allow` only if your app also needs private-network device access
83101

84-
![local-network.png](/assets/imgs/local-network.png)
102+
![local-network.png](/assets/imgs/local-network-access/local-network.png)
85103

86104
> [!NOTE]
87-
> If you're unable to restore functionality after enabling 'Local Network Access,' please contact [Dynamsoft](https://www.dynamsoft.com/contact/).
105+
> Chrome updates permission popup UI frequently. Starting with Dynamic Web TWAIN **v19.3.1**, static screenshots were removed from built-in popups.
106+
> For the latest browser-specific screenshots, see:
107+
> [https://dynamsoft.github.io/Dynamic-Web-TWAIN/local-network-access.html](https://dynamsoft.github.io/Dynamic-Web-TWAIN/local-network-access.html)
88108
89-
***2. (For Admins) To Apply This Setting Across an Enterprise***
109+
***2. (For Admins) Apply this setting across an enterprise***
90110

91-
Enterprise administrators can deploy a Chrome and/or Edge policy to set the "Local Network Access" setting to "Allow" for your website.
111+
Enterprise administrators can deploy Chrome and/or Edge policies to set local-network permission to `Allow` for your website.
92112

93-
Please refer to:
94-
* [Chrome Enterprise Policy List & Management Documentation](https://chromeenterprise.google/policies/#LocalNetworkAccessAllowedForUrls)
95-
* [Microsoft Edge Browser Policy Documentation](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-browser-policies/localnetworkaccessallowedforurls)
113+
Please refer to:
114+
- [Chrome Enterprise Policy List and Management Documentation](https://chromeenterprise.google/policies/#LocalNetworkAccessAllowedForUrls)
115+
- [Microsoft Edge Browser Policy Documentation](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-browser-policies/localnetworkaccessallowedforurls)
96116

97117
***3. Developer Notes***
98118

99-
**a) If Running Inside an `iframe`**
119+
**a) If running inside an `iframe`**
100120

101121
> [!IMPORTANT]
102-
> If Dynamic Web TWAIN is running inside an iframe from a different origin (cross-origin), you must explicitly grant local-network access in the iframe.
103-
> If the iframe is same-origin, no additional configuration is required.
122+
> If Dynamic Web TWAIN runs inside a cross-origin iframe, local-network permissions must be explicitly allowed in the iframe `allow` attribute.
123+
> If the iframe is same-origin, no additional iframe permission configuration is required.
104124
105-
To enable access, specify the `allow` attribute.
106-
For security reasons, it is recommended to allow only the necessary origin rather than using a wildcard.
125+
For Chrome 145+, use `loopback-network` (and `local-network` only if needed). For older versions, include `local-network-access`.
107126

108127
```html
109-
<!-- Recommended: restrict to specific origin -->
110-
<iframe src="..." allow="local-network-access your-domain.com"></iframe>
128+
<!-- Recommended: explicitly list only required origins and permissions -->
129+
<iframe
130+
src="..."
131+
allow="loopback-network https://your-domain.com; local-network https://your-domain.com; local-network-access https://your-domain.com">
132+
</iframe>
111133

112134
<!-- Not recommended: wildcard -->
113-
<!-- <iframe src="..." allow="local-network-access *"></iframe> -->
135+
<!-- <iframe src="..." allow="loopback-network *; local-network *; local-network-access *"></iframe> -->
114136
```
115137

116-
**b) (Optional Enhancement) Permission Check for Improved UX**
138+
**b) (Optional enhancement) Permission check for improved UX**
139+
140+
You can optionally query LNA permissions at runtime. This is not required, but it can help you guide users before initialization fails.
117141

118-
You can optionally query Local Network Access permission at runtime.
119-
This isn’t required, but implementing a check can help you proactively notify users and provide clearer guidance if permission is missing.
120142
```javascript
121-
// Before initializing Dynamsoft WebTWAIN (DWT), you can remind users
122-
// that Chrome may ask for Local Network Access permission.
123-
(async () => {
124-
try {
125-
const result = await navigator.permissions.query({ name: "local-network-access" });
126-
console.log(`LNA permission state: ${result.state}`);
127-
128-
const state = result.state; // 'denied', 'prompt', 'granted'
129-
130-
if (state === "denied") {
131-
const currentSite = encodeURIComponent(window.location.origin);
132-
const settingsUrl = `chrome://settings/content/siteDetails?site=${currentSite}`;
133-
console.log(`Local network access is currently denied.\n\nPlease go to:\n${settingsUrl}\nand enable 'Local network access' permission for this site.`);
134-
// Optionally show a UI guide or help link here.
135-
} else if (state === "prompt") {
136-
alert("To connect with the local scanning service, Chrome will ask for 'Local network access' permission.\n\nPlease click 'Allow' when prompted.");
137-
// Proceed to init DWT after this message.
138-
// e.g., Dynamsoft.DWT.Load() or CreateDWTObjectEx or your init DWT function
139-
} else if (state === "granted") {
140-
console.log("Local network access already granted.");
141-
// Initialize DWT or proceed directly.
142-
// e.g., Dynamsoft.DWT.Load() or CreateDWTObjectEx or your init DWT function
143-
} else {
144-
console.log("Unexpected LNA state:", state);
143+
// Helper: query the first supported permission name from a list.
144+
async function queryFirstSupportedPermission(names) {
145+
for (const name of names) {
146+
try {
147+
const result = await navigator.permissions.query({ name });
148+
return { name, state: result.state };
149+
} catch (_) {
150+
// Not supported in this browser version.
145151
}
146-
147-
} catch (e) {
148-
console.log("This browser does not support Chromium LNA Permissions API yet.");
149-
// Fallback: directly initialize DWT
150-
// Dynamsoft.DWT.Load() or CreateDWTObjectEx or your init DWT function
151152
}
153+
return null;
154+
}
155+
156+
(async () => {
157+
// Chrome 145+: loopback-network; Chrome 142-144: local-network-access.
158+
const loopbackPerm = await queryFirstSupportedPermission([
159+
"loopback-network",
160+
"local-network-access"
161+
]);
162+
163+
if (!loopbackPerm) {
164+
console.log("This browser does not expose the Local Network permission API.");
165+
// Fallback: initialize DWT directly.
166+
return;
167+
}
168+
169+
console.log(`Loopback permission (${loopbackPerm.name}): ${loopbackPerm.state}`);
170+
171+
if (loopbackPerm.state === "denied") {
172+
const currentSite = encodeURIComponent(window.location.origin);
173+
const settingsUrl = `chrome://settings/content/siteDetails?site=${currentSite}`;
174+
console.log(
175+
"Local network permission is denied.\n" +
176+
`Open: ${settingsUrl}\n` +
177+
"Then allow Local Network for this site."
178+
);
179+
return;
180+
}
181+
182+
if (loopbackPerm.state === "prompt") {
183+
alert(
184+
"To connect with the local scanning service, Chrome may ask for Local Network permission. " +
185+
"Please click Allow when prompted."
186+
);
187+
}
188+
189+
// Proceed with DWT initialization.
190+
// e.g., Dynamsoft.DWT.Load() or CreateDWTObjectEx(...)
152191
})();
153192
```
154-
If the permission is not granted, consider displaying a user-friendly message directing them to:
155193

156-
> Chrome → Settings → Privacy and Security → Site Settings → Local network access
194+
If permission is not granted, direct users to:
157195

158-
This approach provides a more polished user experience, especially during onboarding or troubleshooting.
196+
> Chrome -> Settings -> Privacy and security -> Site settings -> Local Network / Apps on device
159197
160198
### Product Improvements Related to Local Network Access
161199

162-
Dynamic Web TWAIN v19.3 introduces **user-experience enhancements** to better surface local service connectivity and permission issues.
200+
Starting from v19.3, Dynamic Web TWAIN now includes UX enhancements to better surface local-service connectivity and permission issues.
163201

164-
These changes **do not alter or bypass Chromium’s security model**. Their purpose is to make permission-related failures easier to identify and understand, and to guide users to the appropriate browser settings when access is blocked.
202+
These changes do not alter or bypass Chromium's security model. They make permission-related failures easier to identify and guide users to the correct browser settings.
165203

166204
The key improvements include:
167205

168-
* **Explicit detection of blocked local network access** \
169-
When the browser blocks communication with the local service, a clear dialog is displayed explaining the cause and directing users to this FAQ.
206+
- **Explicit detection of blocked local network access**
207+
When the browser blocks communication with the local service, a clear dialog explains the cause and directs users to this FAQ.
208+
209+
![prompt blocked](/assets/imgs/local-network-access/prompt-blocked.png)
210+
211+
*Dialog 1 - Permission Guidance*
212+
213+
- **Clearer messaging during service installation**
214+
The service installation dialog explains that connection failure may be caused either by missing service installation or denied local-network permission.
170215

171-
![prompt blocked](/assets/imgs/local-network-access/prompt-blocked.jpg)
172-
173-
*Dialog 1 - Permission Guidance*
174-
175-
* **Clearer messaging during service installation** \
176-
A notice is added to the service installation dialog to inform users that a connection failure may be caused either by the service not being installed or by local network access being denied, as these two cases cannot be reliably distinguished.
216+
![dialog installation](/assets/imgs/local-network-access/service-installation-dialog.png)
177217

178-
![dialog installation](/assets/imgs/local-network-access/service-installation-dialog.png)
218+
*Dialog 2 - Service Installation*
179219

180-
*Dialog 2 - Service Installation*
220+
Clicking "Guide" opens the permission guidance dialog shown above.
181221

182-
Clicking "Guide" opens the permission guidance dialog shown above.
222+
- **Latest popup screenshots hosted externally (v19.3.1+)**
223+
Because Chromium updates native permission popups frequently, static popup screenshots were removed from this FAQ in v19.3.1.
224+
Use this page for the latest screenshots:
225+
[https://dynamsoft.github.io/Dynamic-Web-TWAIN/local-network-access.html](https://dynamsoft.github.io/Dynamic-Web-TWAIN/local-network-access.html)
183226

184-
These improvements are **available starting with Dynamic Web TWAIN v19.3**.
227+
These improvements are available starting with Dynamic Web TWAIN v19.3.
185228

186-
For older versions, a supplemental JavaScript file can be provided upon request by contacting [Dynamsoft Support](mailto:support@dynamsoft.com).
229+
For older versions, a supplemental JavaScript file can be provided on request by contacting [Dynamsoft Support](mailto:support@dynamsoft.com).
187230

188231
> [!NOTE]
189-
> This file improves user guidance only and does not change the underlying browser permission requirements.
232+
> This supplemental JavaScript file improves user guidance only and does not change browser permission requirements.
190233
191234
## Other Causes of Failure to Connect to the Service
192235

193-
There are other causes of service not being connected. You can find them in [another FAQ](/_articles/faq/service-prompting-to-install-repeatedly.md).
236+
There are other causes of service connection failure. See [another FAQ](/_articles/faq/service-prompting-to-install-repeatedly.md).

‎assets/imgs/local-network-access/LNA-prompt.png‎

25.7 KB
Loading

‎assets/imgs/local-network-access/local-network.png‎

44.6 KB
Loading

‎assets/imgs/local-network-access/prompt-blocked.jpg‎

-44.4 KB
Binary file not shown.

‎assets/imgs/local-network-access/prompt-blocked.png‎

23.8 KB
Loading

‎assets/imgs/local-network.png‎

-52.7 KB
Binary file not shown.

0 commit comments

Comments
 (0)