nodejs/node · error

failed to prepare dictionary [%s]\n

Error message

failed to prepare dictionary [%s]\n

What it means

`BrotliEncoderPrepareDictionary()` returned NULL when called during `ReadDictionary` (only in the compress path, `command == COMMAND_COMPRESS`). The dictionary data was read into memory successfully, but the encoder's internal preprocessing of the raw dictionary failed. This is a library-level failure, not a file I/O issue.

Source

Thrown at deps/brotli/c/tools/brotli.c:937

    fclose(f);
    return BROTLI_FALSE;
  }
  bytes_read = fread(buffer, sizeof(uint8_t), context->dictionary_size, f);
  if (bytes_read != context->dictionary_size) {
    free(buffer);
    fprintf(stderr, "failed to read dictionary [%s]: %s\n",
            PrintablePath(context->dictionary_path), strerror(errno));
    fclose(f);
    return BROTLI_FALSE;
  }
  fclose(f);
  context->dictionary = buffer;
  if (command == COMMAND_COMPRESS) {
    context->prepared_dictionary = BrotliEncoderPrepareDictionary(
        BROTLI_SHARED_DICTIONARY_RAW, context->dictionary_size,
        context->dictionary, BROTLI_MAX_QUALITY, NULL, NULL, NULL);
    if (context->prepared_dictionary == NULL) {
      fprintf(stderr, "failed to prepare dictionary [%s]\n",
              PrintablePath(context->dictionary_path));
      return BROTLI_FALSE;
    }
  }
  return BROTLI_TRUE;
}

static BROTLI_BOOL NextFile(Context* context) {
  const char* arg;
  size_t arg_len;

  /* Iterator points to last used arg; increment to search for the next one. */
  context->iterator++;

  context->input_file_length = -1;

  /* No input path; read from console. */
  if (context->input_count == 0) {

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Verify the dictionary file is a valid raw byte sequence and not corrupted.
2. Check for available memory and reduce concurrent memory usage.
3. Rebuild brotli from a known-good source tree and retry.
4. Test with a small known dictionary to isolate whether the issue is dictionary-specific.

// Cannot fully validate at the caller level — this is a library-internal failure.
// Best pre-check: ensure the dictionary is well-formed.
#include <stdbool.h>

bool dictionary_likely_valid(const char *path) {
    // Check file exists, is regular, is within size limits, and is non-empty.
    // A zero-byte dictionary that passes FileSize will still fail PrepareDictionary.
    struct stat st;
    if (stat(path, &st) != 0) return false;
    return S_ISREG(st.st_mode) && st.st_size > 0;
}

When it happens

Trigger: Internal encoder allocation failure while building the prepared dictionary structure; the dictionary data is corrupt or contains patterns the encoder cannot preprocess; a version mismatch between the brotli library and the tool.

Common situations: Using a malformed or empty (zero-byte-sized-but-not-caught) dictionary; memory pressure during dictionary preparation; a custom/patched brotli build with an encoder bug.

Related errors

• dictionary path already set\n
• failed to open dictionary file [%s]: %s\n
• could not get size of dictionary file [%s]
• dictionary [%s] is larger than maximum allowed: %d\n
• could not read dictionary: out of memory\n

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/cceb3de937da2559. Report an issue: GitHub.