microsoft/garnet · critical · GarnetException

Encountered an error when initializing Garnet server. Please

Error message

Encountered an error when initializing Garnet server. Please see log messages above for more details.

What it means

Thrown by the GarnetServer constructor when ServerSettingsManager.TryParseCommandLineArguments returns false and exitGracefully is false. This means the command-line arguments could not be parsed and the error is not a graceful exit condition (like --help). The actual parse errors are logged to the memory logger before this exception is thrown; the message directs you to those preceding logs.

Source

Thrown at libs/host/GarnetServer.cs:99

        public GarnetServer(string[] commandLineArgs, ILoggerFactory loggerFactory = null, bool cleanupDir = false, IAuthenticationSettings authenticationSettingsOverride = null)
        {
            Trace.Listeners.Add(new ConsoleTraceListener());

            // Set up an initial memory logger to log messages from configuration parser into memory.
            using (var memLogProvider = new MemoryLoggerProvider())
            {
                this.initLogger = (MemoryLogger)memLogProvider.CreateLogger("ArgParser");
            }

            if (!ServerSettingsManager.TryParseCommandLineArguments(commandLineArgs, out var serverSettings, out _, out _, out var exitGracefully, logger: this.initLogger))
            {
                if (exitGracefully)
                    Environment.Exit(0);

                // Flush logs from memory logger
                FlushMemoryLogger(this.initLogger, "ArgParser", loggerFactory);

                throw new GarnetException("Encountered an error when initializing Garnet server. Please see log messages above for more details.");
            }

            if (loggerFactory == null)
            {
                // If the main logger factory is created by GarnetServer, it should be disposed when GarnetServer is disposed
                disposeLoggerFactory = true;
            }
            else
            {
                this.initLogger.LogWarning(
                    $"Received an external ILoggerFactory object. The following configuration options are ignored: {nameof(serverSettings.FileLogger)}, {nameof(serverSettings.LogLevel)}, {nameof(serverSettings.DisableConsoleLogger)}.");
            }

            // If no logger factory is given, set up main logger factory based on parsed configuration values,
            // otherwise use given logger factory.
            this.loggerFactory = loggerFactory ?? LoggerFactory.Create(builder =>
            {
                if (!serverSettings.DisableConsoleLogger.GetValueOrDefault())

View on GitHub (pinned to 951b0fc683)

Solutions

Read the log output immediately preceding the exception — it contains the specific parse error from the ArgParser memory logger.
Run the server with --help to see the list of valid command-line arguments for your version.
Fix the malformed or unknown argument in your startup command or container entrypoint.
Validate arguments in deployment scripts against the current version's supported flags.

Example fix

// before: typo in argument name
//   garnet-server --potr 6379

// after:
//   garnet-server --port 6379

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-validate by running a dry parse
if (!ServerSettingsManager.TryParseCommandLineArguments(commandLineArgs, out _, out _, out var exitGracefully, out _))
{
    if (!exitGracefully)
        Console.Error.WriteLine("Invalid command-line arguments. Run with --help for usage.");
}

Try / catch

try
{
    server = new GarnetServer(commandLineArgs, loggerFactory);
}
catch (GarnetException ex) when (ex.Message.Contains("initializing Garnet server"))
{
    logger.LogError(ex, "Garnet server failed to initialize due to invalid arguments. Check logs above.");
    return false;
}

Prevention

Always read the log output above the exception — it contains the specific parse error.
Validate command-line arguments with --help before deploying.
Use deployment templates with pre-validated argument sets.
Test startup commands in staging before production.

When it happens

Trigger: Starting GarnetServer with invalid or malformed command-line arguments that fail parsing (not --help/--version which set exitGracefully=true). Common causes: unknown flags, missing required values, type mismatches in argument values.

Common situations: Deploying with a typo in command-line flags; upgrading Garnet and using removed/renamed CLI arguments; scripting errors in container orchestration that pass wrong arguments; missing values for options that require them.

Related errors

AI-assisted analysis of microsoft/garnet@951b0fc683 (2026-08-13). Data as JSON: /api/errors/9ad05bc225f0df84. Report an issue: GitHub.