Skip to main content

Troubleshooting (macOS)

Common issues and their solutions on macOS. On Windows, see Troubleshooting (Windows).

Three differences from Windows account for most of what you will see here:

  • There is one background process, not a service plus a desktop app.
  • The scanner is reached through Apple's ImageCaptureCore (ICA), which grants one application at a time exclusive use of the scanner.
  • The HTTPS certificate's private key lives in your login keychain, so it is per-user.

For the commands behind these fixes — checking and restarting the service, and where the log files are — see macOS Diagnostics.

Auto-Scan Never Triggers​

Symptom: Auto-scan is enabled and the event stream stays open, but feeding a page does nothing. No images arrive and no error is reported.

Explanation: Auto-scan works by watching the scanner's feeder for paper and starting a scan when a page is detected. On macOS that paper state has to be reported by the scanner's ICA driver, and reporting it is a custom capability of Ambir's own ICA driver for Ambir sheetfed scanners. It is not part of what ICA drivers are generally expected to provide, so an ICA driver from another manufacturer will most likely not report feeder paper state at all — in which case nothing ever appears to change and auto-scan waits indefinitely.

Treat auto-scan on macOS as supported on Ambir sheetfed scanners only. On-demand scanning works on any supported scanner; it is only the automatic trigger that depends on the driver.

Solutions:

  1. Confirm the scanner is an Ambir sheetfed model and that the Ambir ICA Driver is installed. A flatbed has no feeder to watch, and a third-party scanner will generally not drive auto-scan even though it scans correctly on demand.

  2. Check whether paper state is reported at all. Open the scanner, then read it with a page out of the feeder and again with a page inserted:

    await scanner.openSource(name);
    const hasPaper = await scanner.checkPaperLoaded();

    If this returns the same value both ways, the driver is not reporting paper state and auto-scan cannot work on that scanner. Use scan() instead.

  3. Open the scanner before enabling auto-scan. Auto-scan operates on the currently open source; with nothing open, enableAutoScan() returns an error.

  4. Check the service log for the paper poll — see Log Files.

Auto-Scan Stops On Its Own​

Symptom: Auto-scan was working and then quietly stopped capturing.

Explanation: On macOS auto-scan switches itself off after three consecutive scans that fail or return no pages, and — on both platforms — after five minutes in which no page collects any images. This is deliberate: it keeps an abandoned session from scanning into a queue nobody is reading.

Solution: Call disableAutoScan() and then enableAutoScan() again. If it stops repeatedly after three attempts, the underlying scans are failing — work through Scanner Opens But Scan Fails first.

Service Not Responding​

Symptom: checkServiceStatus() returns false, or requests to https://localhost:53052 fail.

Solutions:

  1. Check the service is up:

    curl -sk https://localhost:53052/api/twain/status

  2. If nothing answers, the service may not have started — this is expected if the package was installed while nobody was logged in, in which case it starts at your next login. To start it now:

    "/Library/Application Support/Ambir/ScannerBridge/install-agent.sh"

    Run this as yourself, not with sudo.

  3. To restart it, see Restarting, Stopping and Starting. Note that launchctl stop does not stop this service.

Browser Cannot Connect, Or Reports The Connection Is Not Secure​

Symptom: The page cannot reach https://localhost:53052, or the browser reports the connection is not private. http://localhost:53052 may answer when https:// does not.

Explanation: The service could not find its HTTPS certificate and fell back to plain HTTP. It looks like it started correctly, but browsers will not make the cross-origin call. The certificate is per-user, so this happens when the package was installed under a different account, installed with nobody logged in, or when the certificate command was run with sudo — which puts the private key in root's keychain, where the service can never read it.

Solution: Check for the certificate and, if it is missing, create it for your account as described in Multiple Users and Managed Installs, then restart the service.

security find-certificate -c "ASWCN Scanner Bridge" ~/Library/Keychains/login.keychain-db

Firefox also needs one extra setting.

No Scanners Found​

Symptom: getSources() returns an empty array.

Solutions:

  1. Make sure the scanner is connected, powered on, and its macOS ICA driver is installed. For Ambir scanners that is the Ambir ICA Driver.
  2. Open Apple's Image Capture app. If Image Capture cannot see the scanner either, the problem is the driver or the connection rather than AmbirScan Web Connect.
  3. Quit Image Capture and Preview before scanning from the browser — see Scanner Is In Use By Another Application.
  4. Scanners from manufacturers other than Ambir are listed only when a third-party scanner license is active. Check the license on the admin page.
  5. Scanner discovery on macOS is continuous rather than a one-off lookup, so a scanner plugged in after the page loaded can take a moment to appear. Call getSources() again.

Scanner Is In Use By Another Application​

Symptom: The scanner is listed but openSource() fails, or another Mac app stops being able to use the scanner.

Explanation: macOS gives one application at a time exclusive use of a scanner. Image Capture, Preview and any other scanning app will take the device away from AmbirScan Web Connect, and while a web page has the scanner open the service holds it against them.

Solutions:

  1. Quit Image Capture, Preview and any other scanning software, then try again.

  2. To release the scanner from the service without stopping anything, have the page call closeSource(), or from Terminal:

    curl -sk -X POST https://localhost:53052/api/twain \
      -H 'Content-Type: application/json' \
      -d '{"kind":"twainlocalscanner","method":"closeSource"}'

Scanner Opens But Scan Fails​

Symptom: openSource() succeeds but scan() fails or returns no pages.

Solutions:

  1. Check that paper is loaded (checkPaperLoaded()) and the scanner is online (checkScannerOnline()).
  2. Confirm the scanner can scan outside the browser, from Image Capture. Quit Image Capture again afterwards.
  3. Try a lower resolution or a different colour mode.
  4. Close and re-open the scanner source.
  5. Check the service log — see Log Files.

A Scan Option Appears To Be Ignored​

Symptom: pageSize, jpegQuality, transferMode or the barcode symbology options have no effect.

Explanation: Options that do not apply on macOS are ignored rather than rejected, so the same scan request works on both platforms. The full list is in Platform Differences.

Solution: None needed — this is expected. If your application depends on one of those options, check the table before assuming a defect.

Scan Timeout​

Symptom: A scan request times out or takes too long.

Solutions:

  1. Lower the resolution (200 DPI instead of 600 DPI).
  2. Disable barcode reading and OCR if you do not need them.
  3. Note that requestTimeoutSeconds: 0 means no timeout on Windows but a 300-second timeout on macOS. A scan that needs longer than five minutes will end there.

CORS Errors​

Symptom: The browser console shows CORS-related errors.

The cause and the fix are the same as on Windows — see CORS Errors.

Multiple Browser Tabs​

Symptom: Scanning works in one tab but fails in another.

Explanation: Only one scanner source can be open at a time, and on macOS the operating system enforces exclusive access as well.

Solution: Close the scanner source in the inactive tab before scanning in the active tab, or design your application around single-tab scanning.

Settings And Licensing​

There is no desktop app on macOS. Settings, license activation and the log viewer are on the admin page:

https://localhost:53052/admin

See Licensing and Settings.

Getting Help​

If you're still experiencing issues:

  1. Check the GitHub Issues for known problems
  2. Open a new issue with:
    • Browser and version
    • macOS version, and whether the Mac is Apple Silicon or Intel
    • Scanner model and ICA driver version
    • Error message or screenshot
    • Steps to reproduce
    • The relevant lines from ~/Library/Logs/ASWCN/ScannerBridge/daemon-*.log
  3. Contact Ambir support at support@ambir.com