How to Fix Chromium NSS Initialization Error -8023

Chromium NSS error -8023 maps to SEC_ERROR_PKCS11_DEVICE_ERROR. NSS reports that a PKCS #11 module returned CKR_DEVICE_ERROR, meaning a problem occurred with a token or slot. The code identifies the error class; it does not prove that Chromium’s certificate database is corrupt or identify one universal fix.

The reliable way to resolve it is to identify the exact Chromium build, NSS libraries and modules it loads, packaging model, operating system or serverless runtime, and the last change before the failure. The reports behind this guide describe different environments, so treat each workaround as conditional evidence rather than a guaranteed repair.

What error -8023 means

NSS (Network Security Services) uses PKCS #11 modules to access cryptographic tokens and slots. Error -8023 is the NSS code for SEC_ERROR_PKCS11_DEVICE_ERROR. In practical terms, a loaded PKCS #11 module reported a device-level failure.

Chromium may log both a failure opening a persistent NSS database and a later attempt to initialize NSS without a persistent database. Seeing both messages does not, by itself, show that the database is damaged. Library loading, an incompatible module, an unusual bundled browser package, or a runtime change can produce similar startup symptoms.

Diagnostic checklist

Save the complete startup log, including the first NSS error, the database path (if shown), and every repeated initialization message.
Record the operating-system distribution and version.
Record the Chromium version, how it was installed, and whether it is system Chromium, a wrapper, a container image, an embedded browser, or a serverless binary.
Record the Chromium wrapper or automation package version (for example, the package that launches Chromium).
List recent changes: browser packages, OS updates, container-image rebuilds, copied libraries, environment variables, and serverless runtime updates.
Determine whether the browser package bundles NSS libraries or expects system libraries.

# Chromium version and executable path
chromium --version
command -v chromium

# On distributions that use chromium-browser instead
chromium-browser --version
command -v chromium-browser

# Inspect shared-library dependencies (path varies by installation)
ldd "$(command -v chromium)" | grep -Ei 'nss|nspr|ssl|crypto'

# Show libraries visible to the dynamic linker
ldconfig -p 2>/dev/null | grep -Ei 'libnss3|libnssutil|libnspr'

# Capture the complete launch output
chromium --enable-logging=stderr --v=1 2>&1 | tee chromium-nss.log

Use the executable that your application actually starts. Running a different system Chromium while your wrapper launches a bundled binary can hide the relevant library mismatch.

Check for library and packaging mismatches

System Chromium versus bundled Chromium

First establish whether Chromium uses the operating system’s NSS libraries or copies shipped beside the browser. Embedded and wrapped builds can contain private copies of NSS, NSPR, SQLite, or related libraries. A historical Chromium report involved copied libraries and unusual library directories; it is evidence that custom layouts can matter, not a maintained universal fix.

# Find NSS libraries near a bundled browser (adjust the path)
find /opt /app /usr -type f \( -name 'libnss3.so' -o -name 'libnssutil3.so' -o -name 'libnspr4.so' \) 2>/dev/null

# Inspect the dynamic loader's choice for a specific binary
LD_DEBUG=libs chromium --version 2> loader.log
rg -i 'libnss|libnspr' loader.log

Compare the paths with the package documentation for your distribution or application. Do not delete or rename shared libraries blindly. If a package is designed to use system NSS, removing a bundled copy may be relevant only when your package layout matches the reported case and its maintainers document that arrangement.

Check the expected NSS files

A Debian-era report suspected that Chromium could not find libnss3.so or was using an incorrect library path. That is distribution-specific evidence, but it makes the library lookup a useful check.

# Verify that the files exist and are readable
ls -l /usr/lib*/libnss3.so* /usr/lib*/libnssutil3.so* /usr/lib*/libnspr4.so* 2>/dev/null

# Ask the package manager which package owns them (Debian/Ubuntu)
dpkg -S libnss3.so 2>/dev/null

# Verify package contents (Debian/Ubuntu)
dpkg -V libnss3 2>/dev/null

Install or repair packages using your distribution’s current package instructions. Avoid copying a library from another machine or browser bundle: ABI and dependency differences can create a second failure that is harder to diagnose.

Review recent runtime and image updates

If the error appeared immediately after an update, compare the old and new combinations of Chromium, NSS, the container image, and the runtime. In a 2024 serverless discussion, users associated the timing with a Node.js Lambda runtime update and reported pinning an earlier runtime as a workaround. That report does not establish the underlying change or make rollback a general solution.

Identify the exact runtime version used by the failing deployment.
Reproduce with the previous known-good image or runtime in a disposable environment.
Compare the Chromium binary, NSS files, architecture, and environment variables.
Prefer correcting the incompatible browser/library combination over keeping a permanent rollback.
Document the result and raise the issue with the runtime, package, or wrapper maintainer when the mismatch is outside your application.

Persistent database versus fallback initialization

Some logs mention a failure opening a persistent NSS database, followed by an attempt to initialize NSS without one. These are two initialization paths in the same startup sequence. A fallback message does not prove that deleting the database will help.

Before touching profile data:

Copy the profile and record its location.
Check ownership and permissions for the user running Chromium.
Check whether the profile is on a read-only mount or shared by multiple processes.
Test with a new temporary profile only to separate profile access from system-library loading.

# Disposable profile test; replace the executable if needed
profile_dir="$(mktemp -d)"
chromium --user-data-dir="$profile_dir" --no-first-run --headless about:blank
status=$?
rm -rf "$profile_dir"
exit "$status"

If a fresh profile produces the same -8023 error, the evidence points away from one existing profile database and toward the loaded libraries, module configuration, packaging, or runtime. The sources reviewed do not establish deletion of ~/.pki/nssdb as a general solution, so do not make that your first action.

PKCS #11 modules and hardware tokens

Because -8023 is a PKCS #11 device error, inspect any token, smart-card, HSM, or third-party PKCS #11 module available to the Chromium process. A module can report a device error even when Chromium itself is functioning.

List modules configured for the user and system account that launches Chromium.
Check whether a token or slot is expected in this deployment.
Test with the optional module disabled only in a controlled diagnostic environment.
Compare the result with a clean account or container that has no extra PKCS #11 configuration.

Do not remove security modules from a production host without understanding which applications depend on them. If a module is required, repair its device, permissions, driver, or compatibility with the installed NSS version.

Common symptoms, causes and fixes

Symptom	What it may indicate	Useful next action
Persistent database error followed by “without a persistent database”	Both initialization paths failed; not proof of database corruption	Run the temporary-profile test and inspect libraries and permissions
Failure began after a browser or OS package update	Version or ABI mismatch is possible	Compare package versions and loaded-library paths; use supported package repairs
Only an embedded or wrapped browser fails	Bundled libraries or custom search paths may differ from system Chromium	Inspect the actual launched binary with `ldd` and loader diagnostics
Only a serverless deployment fails	Runtime image changes, architecture, or missing shared libraries	Compare the runtime and image with the last known-good deployment
Only one user account fails	Profile permissions or per-user PKCS #11 configuration	Test a clean profile and inspect ownership and module configuration
Every Chromium build on the host fails	System NSS, NSPR, token, or loader configuration	Verify package files and consult the distribution maintainer with logs

What not to assume

Error -8023 does not identify one corrupt file.
It does not prove that ~/.pki/nssdb must be deleted.
A workaround reported for Lambda, CasparCG, Debian, or a custom Chromium bundle is not automatically safe for another environment.
Removing bundled libraries can make a matching package use system libraries, but doing so on an unrelated package can prevent Chromium from starting.
A successful launch with a temporary profile does not prove that the system NSS installation is healthy; it only narrows the problem to profile access or profile data.

When to escalate

Escalate with a compact, reproducible report when the checks above do not resolve the issue. Include:

Distribution, kernel or base-image version, CPU architecture, and account identity.
Chromium version, source package or wrapper, executable path, and launch arguments.
Complete NSS startup log with timestamps.
Output showing NSS/NSPR library paths and package versions.
Whether a temporary profile changes the result.
Whether a PKCS #11 token or module is installed.
The last package, image, browser, or runtime change before the failure.

Or skip the browser setup

If your goal is simply to capture a page image or PDF, ScreenshotNeo runs the browser capture for you through one GET request. Its cleanup steps accept cookie and consent banners before capture and remove more than 60 known consent platforms, newsletter popups, and chat widgets. Each step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result.

See the ScreenshotNeo API documentation for all capture options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" \\
  -d access_key=YOUR_API_KEY \\
  --data-urlencode url=https://stripe.com \\
  -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const buffer = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', buffer);

ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. It supports full-page and element captures, device presets, custom viewport and retina scale, dark mode, PDF page settings, custom CSS and JavaScript, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, caching, signed links, asynchronous webhooks, bulk capture, usage data, and an OpenAPI specification.

Create a free ScreenshotNeo account: 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots, and every feature is available on every plan.

Performance, reliability and cost notes

Collecting the full startup log and library paths is faster than repeatedly changing profile files without evidence.
Use a disposable profile to isolate profile access while keeping the original profile intact.
Pinning a runtime can restore service temporarily, but investigate the incompatible library or image change before treating it as a permanent fix.
For automated screenshots, browser startup, page load, waits, and resource blocking affect latency. ScreenshotNeo supports waits, caching with a chosen TTL, asynchronous jobs, and bulk capture of up to 100 URLs per call.
ScreenshotNeo bills only clean shots. The X-Page-Verdict and X-Billed response headers show how each response was classified.

FAQ

Is -8023 always caused by a corrupt NSS database?

No. The code is a PKCS #11 device error. Database access can fail at the same time, but the reports do not establish database corruption as the universal cause.

Should I delete `~/.pki/nssdb`?

Not as a first step. Back up the profile, test a temporary profile, and inspect libraries, permissions, modules, and recent updates first.

Can I fix this by installing a random copy of `libnss3.so`?

Do not copy libraries from another machine or browser bundle. Use the package manager and documentation for your distribution, then verify the library path used by the actual Chromium process.

Why does a serverless runtime change matter?

A runtime or base-image update can change the browser, NSS libraries, architecture, or loader environment. Compare the complete old and new deployment rather than assuming the runtime version alone is the cause.

Does ScreenshotNeo remove the need to debug Chromium on my own host?

For ScreenshotNeo captures, the browser runs as part of the service, so your application does not need to package and initialize Chromium locally. Your own Chromium deployment still needs its own diagnosis if you continue running it.