{"record":{"id":"7732c16f8a91e6b5","repo":"questdb/questdb","slug":"async-munmap-is-not-supported-on-windows","errorCode":null,"errorMessage":"Async munmap is not supported on Windows","messagePattern":"Async munmap is not supported on Windows","errorType":"validation","errorClass":"ServerConfigurationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/io/questdb/PropServerConfiguration.java","lineNumber":1817,"sourceCode":"\n            this.maxSqlRecompileAttempts = getInt(properties, env, PropertyKey.CAIRO_SQL_MAX_RECOMPILE_ATTEMPTS, 10);\n\n            String value = getString(properties, env, PropertyKey.CAIRO_WRITER_FO_OPTS, \"o_none\");\n            int lopts = CairoConfiguration.O_NONE;\n            String[] opts = value.split(\"\\\\|\");\n            for (String opt : opts) {\n                int index = WRITE_FO_OPTS.keyIndex(opt.trim());\n                if (index < 0) {\n                    lopts |= WRITE_FO_OPTS.valueAt(index);\n                }\n            }\n            this.writerFileOpenOpts = lopts;\n\n            this.writerMixedIOEnabled = getBoolean(properties, env, PropertyKey.DEBUG_CAIRO_ALLOW_MIXED_IO, ff.allowMixedIO(this.dbRoot));\n            this.fileDescriptorCacheEnabled = getBoolean(properties, env, PropertyKey.CAIRO_FILE_DESCRIPTOR_CACHE_ENABLED, true);\n            this.asyncMunmapEnabled = getBoolean(properties, env, PropertyKey.CAIRO_FILE_ASYNC_MUNMAP_ENABLED, false);\n            if (asyncMunmapEnabled && Os.isWindows()) {\n                throw new ServerConfigurationException(\"Async munmap is not supported on Windows\");\n            }\n            this.rmdirMaxDepth = getInt(properties, env, PropertyKey.CAIRO_RMDIR_MAX_DEPTH, 5);\n\n            this.inputFormatConfiguration = new InputFormatConfiguration(\n                    DateFormatFactory.INSTANCE,\n                    DateLocaleFactory.INSTANCE,\n                    this.locale\n            );\n\n            try (JsonLexer lexer = new JsonLexer(1024, 1024)) {\n                inputFormatConfiguration.parseConfiguration(PropServerConfiguration.class, lexer, confRoot, sqlCopyFormatsFile);\n            }\n\n            String cairoSQLCopyIdSupplier = getString(properties, env, PropertyKey.CAIRO_SQL_COPY_ID_SUPPLIER, \"random\");\n            this.cairoSQLCopyIdSupplier = Chars.equalsLowerCaseAscii(cairoSQLCopyIdSupplier, \"sequential\") ? 1 : 0;\n\n            this.cairoSqlCopyMaxIndexChunkSize = getLongSize(properties, env, PropertyKey.CAIRO_SQL_COPY_MAX_INDEX_CHUNK_SIZE, 100 * Numbers.SIZE_1MB);\n            this.cairoSqlCopyMaxIndexChunkSize -= (cairoSqlCopyMaxIndexChunkSize % CsvFileIndexer.INDEX_ENTRY_SIZE);","sourceCodeStart":1799,"sourceCodeEnd":1835,"githubUrl":"https://github.com/questdb/questdb/blob/6610ab113b84528a73388b0722a38b97f9df78c2/core/src/main/java/io/questdb/PropServerConfiguration.java#L1799-L1835","documentation":"The config flag cairo.file.async.munmap.enabled (PropertyKey.CAIRO_FILE_ASYNC_MUNMAP_ENABLED, default false) enables Windows-specific asynchronous unmapping via the file opener's freed-memory mechanism, which relies on POSIX APIs absent on Windows. PropServerConfiguration hard-rejects the combination when Os.isWindows() is true so the server fails fast instead of crashing later in native code.","triggerScenarios":"Enabling 'cairo.file.async.munmap.enabled=true' (or QDB_CAIRO_FILE_ASYNC_MUNMAP_ENABLED=true) on any Windows host while PropServerConfiguration loads, which happens for ServerMain and for embedded CairoEngine builds that read the same conf root.","commonSituations":"A server.conf copied from a Linux production box to a Windows developer machine or Windows container; CI running Windows jobs against a shared config; enabling the flag globally in a base image that is deployed to mixed-OS fleets.","solutions":["Set cairo.file.async.munmap.enabled=false (or remove the line) on Windows hosts","Keep OS-specific overrides in separate conf files or env layers so the flag is only enabled for Linux deployments","If you manage config via env vars, unset QDB_CAIRO_FILE_ASYNC_MUNMAP_ENABLED in Windows deployment manifests"],"exampleFix":"# before (on Windows)\ncairo.file.async.munmap.enabled=true\n\n# after\ncairo.file.async.munmap.enabled=false","handlingStrategy":"validation","validationCode":"boolean asyncMunmap = Boolean.parseBoolean(firstNonBlank(props.get(\"cairo.file.async.munmap.enabled\"), env.get(\"QDB_CAIRO_FILE_ASYNC_MUNMAP_ENABLED\"), \"false\"));\nif (asyncMunmap && System.getProperty(\"os.name\", \"\").toLowerCase().contains(\"win\")) {\n    throw new IllegalStateException(\"cairo.file.async.munmap.enabled=true is Linux-only\");\n}","typeGuard":null,"tryCatchPattern":"catch (ServerConfigurationException e) { if (e.getMessage().contains(\"Async munmap\")) log.fatal(\"unset cairo.file.async.munmap.enabled on Windows deployments\"); exit(1); }","preventionTips":["Keep OS-specific keys in per-OS config overlays","Flag Linux-only tunables in your config linting so mixed-OS fleets catch them"],"tags":["config","windows","memory-mapped-files","platform","startup"],"backgroundTag":null,"analyzedSha":"6610ab113b84528a73388b0722a38b97f9df78c2","analyzedAt":"2026-08-14T15:30:21.451Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}