Skip to content

Fix "Specified native messaging host not found." in a Chrome extension

6 min readModerok team

What Chrome's docs tell you to check for "Specified native messaging host not found.", the manifest and registry fix, and what breaks after it connects.

If chrome.runtime.connectNative() fails with "Specified native messaging host not found.", the usual fix is a host manifest in the directory Chrome reads, named after the host, whose name matches the string your code passes:

{
  "name": "com.example.my_host",
  "description": "My Application",
  "path": "/usr/local/bin/my_host",
  "type": "stdio",
  "allowed_origins": ["chrome-extension://YOUR_EXTENSION_ID/"]
}

Use your own ID from chrome://extensions, keeping the trailing slash Chrome's example uses. Save the file as com.example.my_host.json in Chrome's default user-level directory, ~/.config/google-chrome/NativeMessagingHosts/ on Linux or ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/ on macOS. On Windows the manifest can live anywhere, with a registry key pointing at it:

reg add "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.example.my_host" /ve /t REG_SZ /d "C:\Program Files\My Application\com.example.my_host.json" /f

A Windows manifest needs a Windows path, such as C:\\Program Files\\My Application\\my_host.exe. The reference: "Path to the native messaging host binary. On Linux and macOS the path must be absolute."

On the extension side, declare the permission and the same name:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "permissions": ["nativeMessaging"],
  "background": { "service_worker": "background.js" }
}
const port = chrome.runtime.connectNative("com.example.my_host");

port.onDisconnect.addListener(() => {
  if (chrome.runtime.lastError) {
    console.error("native host failed:", chrome.runtime.lastError.message);
  } else {
    console.log("native host disconnected");
  }
});

port.postMessage({ text: "ping" });

Chrome's Native messaging page says the "nativeMessaging" permission "must be declared in your extension's manifest file".

The five things Chrome's docs say to check

The page lists five questions under this error. In its order:

  1. "Is the name spelled correctly in the extension and in the manifest file?" The name field is the string your code uses: "Clients pass this string to" runtime.connectNative() or runtime.sendNativeMessage(). It is also constrained: "This name can only contain lowercase alphanumeric characters, underscores and dots". A separate error string covers a bad one, "Invalid native messaging host name specified.", whose documented check is "Check whether the name contains invalid characters."
  2. "On Windows, does the registry key exist under HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE" with the manifest path as its default value? See the next section.
  3. "On macOS and Linux, is the manifest file located in the expected directory and named after the host (such as com.my_company.my_application.json)?" A manifest called my_host.json for host com.example.my_host is not named after the host.
  4. "Is the manifest file in the correct format? In particular, is the JSON valid and well-formed and do the values match the definition of a native messaging host manifest?"
  5. "Does the file specified in path exist? On Windows, paths may be relative, but on macOS and Linux, the paths must be absolute." A missing or relative binary sits under this same error.

On Windows, check both registry views

Chrome's docs name two keys for the manifest path, under HKEY_CURRENT_USER and HKEY_LOCAL_MACHINE, and state a lookup order: "Chrome queries the 32-bit registry view first, then the 64-bit view." An installer that writes only the view it was built for can leave an older entry in the other, so inspect both before concluding the key is missing.

The directory depends on which Chrome is running

Chrome's docs give separate locations for Google Chrome, Google Chrome for Testing and Chromium. On Linux the default user-level directories are ~/.config/google-chrome/NativeMessagingHosts/, ~/.config/google-chrome-for-testing/NativeMessagingHosts/ and ~/.config/chromium/NativeMessagingHosts/, with system-wide equivalents at /etc/opt/chrome/native-messaging-hosts/, /etc/opt/chrome_for_testing/native-messaging-hosts/ and /etc/chromium/native-messaging-hosts/. Those paths are defaults: the docs say "the user-level native messaging hosts are looked up in the NativeMessagingHosts/ subdirectory of the user profile directory", so a run with its own profile looks elsewhere.

Both explain a host that works locally and fails in CI, where a fresh profile and a different build are normal. The build split is also recent: "In versions of Chrome earlier than Chrome 146, Google Chrome for Testing used the same locations as Google Chrome." If you automate extension tests, see testing a Manifest V3 extension with Puppeteer.

Read Chrome's log instead of guessing

Chrome logs the lookup. On Linux:

google-chrome --enable-logging=stderr --log-level=1 2>&1 | grep -E "native_messag|launch_context"

On macOS, use the escaped binary path, /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome. On Windows, start chrome.exe --enable-logging --log-level=1 and tail the log:

$log = "$env:LOCALAPPDATA\Google\Chrome\User Data\chrome_debug.log"
Get-Content -Wait $log | Select-String "native_messag|launch_context"

Use --log-level=1: level 2 suppresses the startup diagnostics. The docs also suggest --user-data-dir="%TEMP%\nm-debug" on Windows, "to launch a separate instance without attaching to an existing Chrome process".

What still breaks after Chrome finds the host

Finding the manifest is only the first gate. Later errors have different causes:

  • "Access to the specified native messaging host is forbidden." The documented check is "Is the extension's origin listed in allowed_origins?" You cannot cover a range: "allowed_origins values can't contain wildcards." Every build with its own ID, including an unpacked dev copy, needs its own entry.
  • "Failed to start native messaging host." The documented check is permissions: "Check whether you have sufficient permissions to execute the native messaging host file."
  • "Native host has exited." The pipe broke before Chrome read the message, and the docs hedge the cause: "This is most likely initiated from your native messaging host."
  • "Error when communicating with the native messaging host." Per the docs, "This indicates an incorrect implementation of the communication protocol in the native messaging host." Each message "is serialized using JSON, UTF-8 encoded and is preceded with 32-bit" length in native byte order, and the page's tips cover the rest: keep stdout clean, use the right byte order, count bytes not characters, and set O_BINARY on Windows. Sizes are capped asymmetrically: "The maximum size of a single message from the native messaging host is 1 MB" and "The maximum size of the message sent to the native messaging host is 64 MiB."

Two structural limits matter early. Native messaging is unavailable where many people first try it: "These methods are not available inside content scripts, only inside your extension's pages and service worker." And the two calls differ: connectNative() starts a host and "keeps it running until the port is destroyed", while with sendNativeMessage(), "Chrome starts a new native messaging host process for each message."

The port also affects service worker lifetime. Chrome's service worker lifecycle page notes that from Chrome 105 "Connecting to a native messaging host using browser.runtime.connectNative() will keep a service worker alive", then gives the failure mode: "If the host process crashes or is shut down, the port is closed and the service worker will terminate after timers complete." Its advice: "Guard against this by calling browser.runtime.connectNative() in the port's onDisconnect event handler."

Firefox differences

A cross-browser host needs a second manifest, not a copy of the first. MDN's native manifests page documents a different allow-list key: allowed_extensions holds "An array of Add-on ID values", not origins, and the same page adds: "This means you want to include the browser_specific_settings key in your extension's manifest.json file so you set an explicit ID during development."

The locations differ too. Firefox reads ~/.mozilla/native-messaging-hosts/<name>.json on Linux and ~/Library/Application Support/Mozilla/NativeMessagingHosts/<name>.json on macOS, and on Windows the key is HKEY_CURRENT_USER\SOFTWARE\Mozilla\NativeMessagingHosts\<name> (MDN warns that "As of Firefox 64, the 32-bit registry view Wow6432Node will be checked first"). The name rule is looser, allowing "(lowercase or uppercase) alphanumeric characters, underscores, and dots".

Error strings differ too, so Chrome's wording finds nothing. MDN's native messaging page lists "No such native application <name>" and "This extension does not have permission to use native application <name>", gives the size limits as 1 MB from the application and 4 GB to it, and notes a debugging convenience: "If the native application sends any output to stderr, the browser will redirect it to the browser console."

Seeing these failures on real machines

Several causes live on the user's machine: their registry view, their permissions, their build of Chrome. You will not reproduce those locally, and your extension sees them only as a disconnect with chrome.runtime.lastError set. That is the case worth reporting, and what Moderok.captureLastError() is for:

import { Moderok } from "@moderok/sdk";

// Moderok.init() runs earlier, at the top of the same service worker.
port.onDisconnect.addListener(() => {
  Moderok.captureLastError("runtime.connectNative", chrome.runtime.lastError, {
    host: "com.example.my_host",
  });
});

The SDK needs the storage permission next to nativeMessaging. It records nothing when the port closed cleanly with no lastError set, so this is safe in the same handler, and each recorded error carries the SDK's event context, including the operating system, so a Windows registry problem reads differently from a macOS path problem. The same pattern fits every callback-style API, which we covered in catching chrome.runtime.lastError in a service worker.