microsoft/garnet · error · ACLException

Unable to parse ACL rule {exception.Filename}:{exception.Lin

Error message

Unable to parse ACL rule {exception.Filename}:{exception.Line}:  {exception.Message}

What it means

Thrown by AccessControlList.Load() when a line in the ACL configuration file fails to parse. The inner ACLParsingException is rewrapped as an ACLException that includes the filename, the 1-based line number, and the original parser message. The load is atomic: if parsing fails the existing rules are left untouched (the temporary ACL is discarded).

Source

Thrown at libs/server/ACL/AccessControlList.cs:203

            try
            {
                streamReader = new StreamReader(File.OpenRead(aclConfigurationFile), Encoding.UTF8, true);
            }
            catch
            {
                throw new ACLException($"Unable to open ACL configuration file '{aclConfigurationFile}'");
            }

            // Remove default user and load statements
            try
            {
                acl._userHandles.Clear();
                acl.Import(streamReader, aclConfigurationFile);
            }
            catch (ACLParsingException exception)
            {
                throw new ACLException($"Unable to parse ACL rule {exception.Filename}:{exception.Line}:  {exception.Message}");
            }
            finally
            {
                streamReader.Close();
            }

            // Add back default user and update the cached default user handle
            _defaultUserHandle = acl.CreateDefaultUserHandle(defaultPassword);

            // Atomically replace the user list
            _userHandles = acl._userHandles;
        }

        /// <summary>
        /// Save current
        /// </summary>
        /// <param name="aclConfigurationFile"></param>
        public void Save(string aclConfigurationFile)

View on GitHub (pinned to 951b0fc683)

Solutions

1. Read the full error message: it names the file and the exact line number — open that line and fix the syntax error.
2. Validate against Garnet's supported ACL rule grammar (user, on/off, >password, +@category, +command, allcommands/nocommands, etc.).
3. Use the ACL SETUSER command at runtime instead of editing the file directly, then SAVE to persist a known-good file.
4. If upgrading, check the release notes for ACL grammar changes and migrate affected rules.

Example fix

// before (malformed line in acl.conf):
//   user default on >secretpass +@all +@nonexistent
// after:
//   user default on >secretpass +@all +@read +@write

// Validate ACL file is parseable before startup by dry-loading
if (!File.Exists(aclFile)) throw new FileNotFoundException(aclFile);
var lines = File.ReadAllLines(aclFile);
foreach (var (line, idx) in lines.Select((l, i) => (l, i)))
{
    var trimmed = line.Trim();
    if (trimmed.Length == 0 || trimmed.StartsWith('#')) continue;
    // ACLParser.ParseACLRule is internal; validate via a staging ACL load instead
}

try
{
    acl.Load(defaultPassword, aclConfigurationFile);
}
catch (ACLException ex)
{
    // ex.Message contains file:line:detail — surface to operator, keep old rules
    logger.LogError(ex, "ACL file load failed; retaining previous rules");
    throw;
}

When it happens

Trigger: Calling AccessControlList.Load(defaultPassword, aclConfigurationFile) where the file contains a malformed ACL rule line (e.g. 'user default on >password invalidrule', an unrecognized category like '+@nosuchcat', or an unterminated password token). ACLParser.ParseACLRule throws ACLException for each syntax violation, Import() wraps it in ACLParsingException with the line number, and Load() re-throws as ACLException.

Common situations: Hand-editing the ACL config file and introducing a typo; upgrading Garnet and using a rule keyword that was renamed or removed; pasting a Redis ACL file that uses a syntax Garnet's parser doesn't support; encoding issues (non-UTF-8 BOM) confusing the tokenizer.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• {exception.Message}
• Gossip sample fraction should be in range [0,100]
• Cannot use AzureStorage device without supplying storage-str
• Cannot use AzureStorage device with both storage-string and
• Invalid endpoint format {Address} {Port}.

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