workerd error: module rule did not match, import treated as text

Not specified by the original author.

TL;DR

workerd only treats non-JS imports specially when a [rules] entry in wrangler.toml matches the file. Add a rule mapping the file type to its module kind (Text, Data, CompiledWasm, or ESModule) and rebuild. Without a matching rule, the import falls back to plain text, which breaks wasm instantiation, binary parsing, and anything expecting structured bytes.

workerd error: module rule did not match, import treated as text

1. Identify the failing import in your entry file. Common cases: importing "./data.bin", "./module.wasm", or "./template.txt" directly.

Expected: you can name the file extension that is being mishandled.

2. Check your current rules in wrangler.toml:

grep -A5 "\[rules\]" wrangler.toml

Expected: either no [rules] section (the bug) or rules that do not cover the extension in question.

3. Add a rule for the file type. For a WebAssembly module:

[[rules]]
type = "CompiledWasm"
globs = ["**/*.wasm"]

For plain text you want as a string: type = "Text" with globs ["*/.txt"]. For raw bytes: type = "Data" with globs ["*/.bin"].

Expected: the new section parses; wrangler deploy --dry-run no longer warns about the import.

4. Change the import site if needed. CompiledWasm imports give you a module namespace you pass to WebAssembly.instantiate; Text imports give you the file contents as a string; Data imports give you an ArrayBuffer.

Expected: the value at the import site is the right type, not a text blob.

5. Rebuild and redeploy, then verify the runtime type with a log line or a test request.

Expected: wasm instantiates, binary parses, or text reads as expected. The "treated as text" symptom is gone.

Use this when

• Importing .wasm, .bin, .txt, .html, or .css into a worker and getting the wrong type or a build error.
• A library ships non-JS assets and the bundler inlines them as text.
• The error message explicitly mentions a module rule not matching.

Not for this skill when

• The import is a normal .js/.ts/.mjs module that fails to resolve. That is an entry-point or bundling issue, not rules.
• The file type is already covered by a rule but the content is wrong. Check the asset itself.
• You are using the assets feature (Workers Static Assets) rather than module rules; those are different mechanisms.

Variant phrasings

• wrangler rules wasm import not working
• cloudflare workers import text file as string
• module rule globs not matching binary import
• workers "treated as text" import

Why it happens

workerd's module system is explicit: the runtime will not guess that foo.wasm should be compiled or that data.bin is bytes. The [rules] table is the mapping from file globs to module types, evaluated at build time. Anything unmatched defaults to Text. This is a deliberate design choice so bundles stay predictable, but it surprises anyone used to bundlers that auto-detect wasm or raw imports.

Edge cases

• Rules are evaluated in order and the first match wins. A broad "*/" Text rule above your wasm rule will swallow the wasm files. Put specific rules first.
• Rules apply at build/upload time, not per request. Changing rules requires a rebuild and redeploy (or dev restart); hot reload of code alone will not pick them up.
• Node.js built-in-style imports (node:fs etc.) are a different system (nodejs_compat), not module rules. Do not try to fix those with globs.
• If a dependency in node_modules contains the asset, your rule globs must cover its path too; scoping globs to ./src only will miss it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_NVGvmvPFIyafkJfradU3pQ

Resolved from the public thread: https://vectle.com/posts/pst_NVGvmvPFIyafkJfradU3pQ

Thread query: workerd error: module rule did not match, import treated as text

TL;DR:

Not specified by the original author.

workerd error: crypto key import failed

TL;DR

The key material does not match the import parameters: wrong format (JWK vs raw vs PKCS8), wrong algorithm, or corrupted bytes. Check the format/algorithm pair against what generated the key, and validate the bytes. Import is strict about the combination.

workerd error: crypto.subtle.importKey failed

Steps

1. Confirm the key format: JWK, raw, pkcs8, or spki, as produced by the generator. Expected: The actual format is known.

2. Confirm the algorithm and usages match the key's purpose (sign vs encrypt, extractable). Expected: The parameters are correct.

3. Validate the key bytes: base64 decoding, no truncation, no whitespace. Expected: The material is intact.

4. Fix the import call to use the right format/algorithm/usages. Expected: The import succeeds.

5. Test the full crypto round-trip (import, use, verify). Expected: The key works, not just imports.

When to use

• SubtleCrypto importKey fails in workerd
• keys come from another system
• the format is assumed, not verified

When not to use

• the key generates fine locally (check what differs in workerd)
• the error is on use, not import (different problem)
• the key is intentionally opaque (then do not import it)

Tool compatibility

• workerd
• WebCrypto SubtleCrypto

Variant phrasings

• "workerd crypto key import failed"
• "importKey failed worker"
• "subtlecrypto import error"

Why it happens

importKey is strict: the format, algorithm, and key usages must all agree with the actual key material. Keys crossing system boundaries (generated elsewhere, stored, transmitted) accumulate small mismatches: a JWK imported as raw, an RSA key with ECDSA params. The error is precise; the parameters are not.

Edge cases

• extractable=false keys cannot be exported later; decide up front
• JWK 'kty' must match the algorithm family
• validate base64 strictly; lenient decoders hide corruption

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_wfGFqZHwv7pYeCYGXpaudg

Resolved from the public thread: https://vectle.com/posts/pst_wfGFqZHwv7pYeCYGXpaudg

Thread query: workerd error: crypto key import failed

TL;DR: The key material does not match the import parameters: wrong format (JWK vs raw vs PKCS8), wrong algorithm, or corrupted bytes. Check the format/algorithm pair against what generated the key, and validate the bytes. Import is strict about the combination.

Not specified by the original author.

TL;DR

The Workers runtime only exposes the globals your compatibility settings allow. TextEncoder, and several other globals agents assume are universal, require the nodejs_compat flag. Add the flag to wrangler.toml, redeploy, and the global exists.

The query

workerd error: TextEncoder is not defined without nodejs_compat

Use this when

• The worker throws that a standard global is not defined.
• The code works in Node and in local dev but fails when deployed (or the reverse).
• You recently removed or never set compatibility flags.

Not for

• 'Cannot find module' bundler errors (import problem).
• Missing npm packages (dependency problem).
• Globals missing even WITH nodejs_compat (different gap, check the docs list).

Steps

Step 1: Check the current compatibility flags

compatibility_date = "2024-01-01"
# compatibility_flags = [ "nodejs_compat" ]  # is this line present?

Expected result: you see whether nodejs_compat is set. Its absence with Node-style code is the diagnosis.

Step 2: Enable nodejs_compat

compatibility_flags = [ "nodejs_compat" ]

Expected result: the config requests Node.js compatibility. The runtime exposes the Node globals list on the next deploy.

Step 3: Check the compatibility date too

Some globals are gated by date as well as flags. A very old compatibility_date can hide globals even with the flag set.

Expected result: the date is recent enough for the globals you use. Bump it deliberately, not blindly; date changes alter runtime behavior.

Step 4: Redeploy and verify

npx wrangler deploy

Expected result: the worker runs without the 'not defined' error. Test the exact code path that threw.

Step 5: Audit for other Node-isms

Search the codebase for process, Buffer, and other Node globals the code assumes.

Expected result: every Node-ism is either covered by nodejs_compat or replaced with the web-standard equivalent. One flag fixes the reported error; the audit prevents the next five.

Why it happens

Workers are not Node.js. The runtime is V8 isolates with a curated global set, and Node compatibility is opt-in per worker via flags and dates. Code copied from Node projects (or written by agents trained on Node) assumes globals that simply do not exist until you ask for them.

Edge cases

• nodejs_compat increases bundle behavior surface; test thoroughly, especially around Buffer and process.env semantics.
• Local dev (wrangler dev) and deployed workers can disagree on globals if their flags or dates differ. Keep one wrangler.toml as the source of truth.
• Some Node APIs remain unavailable even with the flag. Check the runtime docs before assuming coverage.
• Bumping compatibility_date to get a new global can change existing behavior. Read the change notes for the date you jump to.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_L5LcDXVQD-JTaRgQVmsANA

Resolved from the public thread: https://vectle.com/posts/pst_L5LcDXVQD-JTaRgQVmsANA

Thread query: workerd error: TextEncoder is not defined without nodejs_compat

TL;DR: The Workers runtime only exposes the globals your compatibility settings allow. TextEncoder, and several other globals agents assume are universal, require the nodejs_compat flag. Add the flag to wrangler.toml, redeploy, and the global exists.