microsoft/garnet · error · ACLException

Unable to open ACL configuration file '{aclConfigurationFile

Error message

Unable to open ACL configuration file '{aclConfigurationFile}'

What it means

Thrown by AccessControlList.Load when opening the ACL file with new StreamReader(File.OpenRead(...)) throws any exception. The file exists (the earlier check passed) but could not be opened for reading — typically an IO/permission/sharing error. The original exception is swallowed and rethrown as an ACLException with the path.

Source

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

        public void Load(string defaultPassword, string aclConfigurationFile)
        {
            // Attempt to load ACL configuration file
            if (!File.Exists(aclConfigurationFile))
            {
                throw new ACLException($"Cannot find ACL configuration file '{aclConfigurationFile}'");
            }

            // Import file into a new temporary access control list to guarantee atomicity
            AccessControlList acl = new();
            StreamReader streamReader;

            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

View on GitHub (pinned to 951b0fc683)

Solutions

Ensure the process has read permission on the ACL file.
Avoid concurrent cross-process read/write of the same ACL file, or use a separate atomic rename pattern for writes.
Retry once after a brief delay if the file is likely transiently locked.
Confirm the path is a file, not a directory (File.Exists returns true for files only, but a race could change type).

Example fix

// before
acl.Load(defaultPassword, aclFile);

// after
try {
    acl.Load(defaultPassword, aclFile);
} catch (ACLException ex) when (ex.Message.Contains("Unable to open")) {
    logger.LogWarning(ex, "ACL file locked/unreadable, retrying");
    Thread.Sleep(100);
    acl.Load(defaultPassword, aclFile);
}

Defensive patterns

Strategy: retry

Validate before calling

try { using var _ = File.OpenRead(aclConfigurationFile); }
catch { throw new IOException("ACL file cannot be opened for reading."); }

Type guard

static bool IsReadable(string path)
{
    try { using var _ = File.OpenRead(path); return true; } catch { return false; }
}

Try / catch

for (int attempt = 0; attempt < 2; attempt++)
{
    try { acl.Load(defaultPassword, aclConfigurationFile); break; }
    catch (ACLException ex) when (attempt == 0 && ex.Message.Contains("Unable to open")) { Thread.Sleep(100); continue; }
}

Prevention

Ensure read permission on the ACL file.
Use atomic temp-file+rename for writes to avoid cross-process locks.
Confirm the path is a file, not a directory.
Briefly retry on transient locks (e.g. antivirus).

When it happens

Trigger: The file exists but is locked exclusively by another process/writer; the process lacks read permission; the path is a directory; or an IO error occurs at open time (e.g. removable media not ready).

Common situations: The ACL file is being concurrently rewritten by the Save method (which holds a lock on 'this' but not on the OS file across processes); a permissions change between the File.Exists check and OpenRead; antivirus locking the file on Windows; the path is a directory.

Related errors

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