What causes "Error mapping file: %s " in mono/mono?

Rebuild the bundle with mkbundle to ensure it is not corrupted or truncated.

Error mapping file: %s

Error message

Error mapping file: %s

What it means

Fatal error (exit 1) in Mono's bundled-application (mkbundle) loader when mono_file_map_error fails to memory-map a region of the embedded bundle. If an error message is returned it is printed via `%s`; otherwise perror prints the OS errno. The bundle cannot be unpacked, so startup aborts.

Source

Thrown at mono/mini/main.c:279

	for (i = 0; i < items; i++){
		char *kind;
		int strsize = STREAM_INT (p);
		uint64_t offset;
		uint32_t item_size;
		kind = p+4;
		p += 4 + strsize;
		offset = STREAM_LONG(p);
		p += 8;
		item_size = STREAM_INT (p);
		p += 4;
		
		if (mapaddress == NULL) {
			char *error_message = NULL;
			mapaddress = (guchar*)mono_file_map_error (directory_location - offset, MONO_MMAP_READ | MONO_MMAP_PRIVATE,
				fd, offset, &maphandle, program, &error_message);
			if (mapaddress == NULL) {
				if (error_message)
					fprintf (stderr, "Error mapping file: %s\n", error_message);
				else
					perror ("Error mapping file");
				exit (1);
			}
			baseline = offset;
		}
		if (strncmp (kind, "assembly:", strlen ("assembly:")) == 0){
			char *aname = kind + strlen ("assembly:");
			MonoBundledAssembly mba = { aname, mapaddress + offset - baseline, item_size }, *ptr;
			ptr = g_new (MonoBundledAssembly, 1);
			memcpy (ptr, &mba, sizeof (MonoBundledAssembly));
			g_array_append_val  (assemblies, ptr);
			if (entry_point == NULL)
				entry_point = aname;
		} else if (strncmp (kind, "config:", strlen ("config:")) == 0){
			char *config = kind + strlen ("config:");
			char *aname = g_strdup (config);
			aname [strlen(aname)-strlen(".config")] = 0;

View on GitHub (pinned to 0f53e9e151)

Solutions

Rebuild the bundle with mkbundle to ensure it is not corrupted or truncated.
Check system limits (ulimit -v, /proc/sys/vm/max_map_count) and free file descriptors.
Ensure the bundle was built for the correct target architecture and run on a compatible system.

Example fix

// before
./mybundle   # corrupted/truncated -> Error mapping file

// after
mkbundle -o mybundle MyApp.exe --static   # rebuild
./mybundle

Defensive patterns

Strategy: validation

Validate before calling

// Verify the bundle file integrity/size before executing.
const fs = require('fs');
function bundleLooksOk(p) {
  try {
    const st = fs.statSync(p);
    return st.isFile() && st.size > 0 && fs.accessSync(p, fs.constants.R_OK) === undefined;
  } catch { return false; }
}
if (!bundleLooksOk(bundlePath)) console.error('Bundle missing/empty/unreadable; rebuild with mkbundle.');

Try / catch

// mmap failure -> exit(1); catch across child process.
try {
  cp.execFileSync('./mybundle', { stdio: 'pipe' });
} catch (e) {
  if (/Error mapping file/.test(String(e.stderr))) {
    console.error('Bundle mmap failed; check corruption, limits, fs support.');
  }
}

Prevention

Rebuild bundles with mkbundle whenever the Mono runtime version changes.
Check `ulimit -v` and `/proc/sys/vm/max_map_count` before running large bundles.
Run bundles on filesystems that support mmap.

When it happens

Trigger: mkbundle-embedded application where mmap of an assembly/config region fails (mono_file_map_error returns NULL). error_message non-NULL triggers this fprintf.

Common situations: Corrupted or truncated bundled binary, mmap limits exceeded, file descriptor exhaustion, or a bundle built for a different platform/architecture. Running on a filesystem that does not support mmap.

Related errors

AI-assisted analysis of mono/mono@0f53e9e151 (2026-08-13). Data as JSON: /api/errors/b05a2f0cc9ce19a3. Report an issue: GitHub.