How to fix Error 5503 on Windows Server 2025 / Windows 11

by

Troubleshooting Guide: Error 5503 – FILESTREAM File Entry Not Found in sys.database_files

Why This Error Happens

This error occurs when SQL Server’s internal metadata catalog (sys.database_files) does not contain a corresponding record for a FILESTREAM data container that the Database Engine is attempting to access. This mismatch is typically caused by an inconsistent or corrupted FILESTREAM filegroup directory structure, a database that was restored or attached without properly migrating the underlying FILESTREAM data folders, or manual deletion/modification of files within the FILESTREAM data container outside of SQL Server. In Windows Server 2025 environments, this can also surface after an abrupt failover or improper VSS-based snapshot restore that leaves the NTFS/ReFS folder GUIDs out of sync with the database metadata.

Step-by-Step Resolution Guide

Step 1: Verify FILESTREAM Configuration at the Instance Level

  • Open SQL Server Configuration Manager on Windows Server 2025 and confirm FILESTREAM is enabled for the instance (SQL Server Services > right-click instance > Properties > FILESTREAM tab).
  • Ensure “Enable FILESTREAM for Transact-SQL access” and “Allow remote clients access to FILESTREAM data” are checked if remote access is required.
  • Run the following query to confirm the instance-level setting is active:
EXEC sp_configure 'filestream access level';

Step 2: Inspect the sys.database_files Metadata

  • Query the catalog view to identify the missing or mismatched entry:
SELECT file_id, type_desc, name, physical_name 
FROM sys.database_files 
WHERE type_desc = 'FILESTREAM';
  • Cross-reference the physical_name path with the actual folder structure on disk (e.g., D:\SQLData\FileStreamContainer\).
  • If the folder exists on disk but is missing from this view, the metadata is desynchronized and requires a filegroup repair.

Step 3: Repair or Re-add the FILESTREAM Filegroup

  • If the physical folder is missing or corrupted, remove the orphaned reference and re-add the file:
ALTER DATABASE YourDB 
REMOVE FILE FileStreamLogicalName;

ALTER DATABASE YourDB 
ADD FILE (NAME = FileStreamLogicalName, FILENAME = 'D:\SQLData\FileStreamContainer_New') 
TO FILEGROUP FileStreamGroup;
  • If the folder exists but Windows NTFS permissions are blocking access, grant the SQL Server service account full control via File Explorer > Properties > Security or via PowerShell:
icacls "D:\SQLData\FileStreamContainer" /grant "NT SERVICE\MSSQLSERVER:(OI)(CI)F"

Step 4: Restart the SQL Server Service and Validate Database State

  • Restart the SQL Server (MSSQLSERVER) service via Services.msc or PowerShell:
Restart-Service -Name 'MSSQLSERVER' -Force
  • Run DBCC CHECKDB (YourDB) WITH NO_INFOMSGS, ALL_ERRORMSGS; to confirm no further structural corruption exists in the FILESTREAM filegroup.

Alternative or Verification Steps

  • Confirm the fix by inserting/retrieving a test FILESTREAM record using a client application or OPENROWSET(BULK...) to ensure the file handle resolves correctly.
  • If the error persists, restore the database from the last known good backup (full + log chain) taken prior to the FILESTREAM corruption event, ensuring the FILESTREAM container path is restored to its original location.