{"record":{"id":"a55824b6902fa31d","repo":"dotnet/runtime","slug":"max-heap-size-must-be-at-least-dmb-n","errorCode":null,"errorMessage":"max-heap-size must be at least %dMb.\\n","messagePattern":"max-heap-size must be at least (.+?)Mb\\.\\\\n","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"src/mono/mono/metadata/boehm-gc.c","lineNumber":171,"sourceCode":"\n\tGC_set_warn_proc (mono_gc_warning);\n\tGC_set_finalize_on_demand (1);\n\tGC_set_finalizer_notifier(mono_gc_finalize_notify);\n\n\tGC_init_gcj_malloc (5, NULL);\n\tGC_allow_register_threads ();\n\n\tif ((env = g_getenv (\"MONO_GC_PARAMS\"))) {\n\t\tchar **ptr, **opts = g_strsplit (env, \",\", -1);\n\t\tfor (ptr = opts; *ptr; ++ptr) {\n\t\t\tchar *opt = *ptr;\n\t\t\tif (g_str_has_prefix (opt, \"max-heap-size=\")) {\n\t\t\t\tsize_t max_heap;\n\n\t\t\t\topt = strchr (opt, '=') + 1;\n\t\t\t\tif (*opt && mono_gc_parse_environment_string_extract_number (opt, &max_heap)) {\n\t\t\t\t\tif (max_heap < MIN_BOEHM_MAX_HEAP_SIZE) {\n\t\t\t\t\t\tfprintf (stderr, \"max-heap-size must be at least %dMb.\\n\", MIN_BOEHM_MAX_HEAP_SIZE_IN_MB);\n\t\t\t\t\t\texit (1);\n\t\t\t\t\t}\n\t\t\t\t\tGC_set_max_heap_size (max_heap);\n\t\t\t\t} else {\n\t\t\t\t\tfprintf (stderr, \"max-heap-size must be an integer.\\n\");\n\t\t\t\t\texit (1);\n\t\t\t\t}\n\t\t\t\tcontinue;\n\t\t\t} else if (g_str_has_prefix (opt, \"toggleref-test\")) {\n\t\t\t\tregister_test_toggleref_callback ();\n\t\t\t\tcontinue;\n\t\t\t} else {\n\t\t\t\t/* Could be a parameter for sgen */\n\t\t\t\t/*\n\t\t\t\tfprintf (stderr, \"MONO_GC_PARAMS must be a comma-delimited list of one or more of the following:\\n\");\n\t\t\t\tfprintf (stderr, \"  max-heap-size=N (where N is an integer, possibly with a k, m or a g suffix)\\n\");\n\t\t\t\texit (1);\n\t\t\t\t*/","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/dotnet/runtime/blob/60108ba66eb7d1d12f595480091b4ad80a24b172/src/mono/mono/metadata/boehm-gc.c#L153-L189","documentation":"During Mono's Boehm GC initialization the runtime parses the MONO_GC_PARAMS environment variable. The max-heap-size option is accepted only if its value is at least MIN_BOEHM_MAX_HEAP_SIZE_IN_MB (16 MB). Below that, the GC refuses to start and prints this message followed by exit(1), because a smaller heap would be unusable/contradict GC internals.","triggerScenarios":"Launching a Mono (Boehm GC) process with MONO_GC_PARAMS containing max-heap-size=N where N parses to fewer than 16 megabytes (e.g. max-heap-size=8, max-heap-size=10m, max-heap-size=1m). The check fires at GC init, before user code runs.","commonSituations":"Trying to constrain memory tightly on embedded/container workloads and setting an unrealistically small ceiling; typos or wrong unit suffix (max-heap-size=16k meaning 16 kilobytes); copying a config from a sgen-tuned app where smaller numbers were intended.","solutions":["Set max-heap-size to at least 16m, e.g. MONO_GC_PARAMS=max-heap-size=64m, and tune upward if the app needs headroom.","Remove max-heap-size from MONO_GC_PARAMS if no hard ceiling is required.","Switch to sgen (MONO_GC_PARAMS=sgen) if you need finer-grained or smaller-heap control, as this limit is Boehm-specific.","Validate the number suffix: bare N is megabytes; k/m/g suffixes multiply, so 16m is 16 MB and 16k is far below the floor."],"exampleFix":"# before\nexport MONO_GC_PARAMS=max-heap-size=8m\n\n# after\nexport MONO_GC_PARAMS=max-heap-size=64m","handlingStrategy":"validation","validationCode":"#!/usr/bin/env bash\n# Validate MONO_GC_PARAMS max-heap-size is >= 16MB before launching Mono (Boehm).\nset -euo pipefail\nval=\"${MONO_GC_PARAMS:-}\"\nif [[ \"$val\" =~ max-heap-size=([0-9]+)([kKmMgG]?) ]]; then\n  num=\"${BASH_REMATCH[1]}\"; unit=\"${BASH_REMATCH[2]}\"\n  case \"$unit\" in\n    k|K) mb=$(( num / 1024 ));;\n    g|G) mb=$(( num * 1024 ));;\n    *)   mb=\"$num\";;\n  esac\n  [ \"$mb\" -ge 16 ] || { echo \"max-heap-size must be >=16m\"; exit 1; }\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set max-heap-size to at least 16m (the Boehm floor).","Remember a bare number is megabytes; use the m suffix explicitly.","Prefer sgen if you need fine-grained or smaller-heap control.","Validate MONO_GC_PARAMS in deployment scripts before app launch."],"tags":["mono","boehm-gc","gc","configuration","environment-variable","startup"],"backgroundTag":null,"analyzedSha":"60108ba66eb7d1d12f595480091b4ad80a24b172","analyzedAt":"2026-08-10T18:54:11.478Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}