{"record":{"id":"4f11291c4c37990e","repo":"litedb-org/LiteDB","slug":"0-4f1129","errorCode":"0","errorMessage":"Collection ${this.Name} requires string as 'filename' or a document field 'filename'","messagePattern":"Collection (.+?) requires string as 'filename' or a document field 'filename'","errorType":"exception","errorClass":"LiteException","httpStatus":null,"severity":"error","filePath":"LiteDB/Engine/SystemCollections/SysFileJson.cs","lineNumber":18,"sourceCode":"using System;\nusing System.Collections.Generic;\nusing System.IO;\nusing System.Linq;\nusing System.Text;\nusing static LiteDB.Constants;\n\nnamespace LiteDB.Engine\n{\n    internal class SysFileJson : SystemCollection\n    {\n        public SysFileJson() : base(\"$file_json\")\n        {\n        }\n\n        public override IEnumerable<BsonDocument> Input(BsonValue options)\n        {\n            var filename = GetOption(options, \"filename\")?.AsString ?? throw new LiteException(0, $\"Collection ${this.Name} requires string as 'filename' or a document field 'filename'\");\n            var encoding = GetOption(options, \"encoding\", \"utf-8\").AsString;\n\n            using (var fs = new FileStream(filename, FileMode.Open, FileAccess.Read, FileShare.ReadWrite))\n            {\n                using (var reader = new StreamReader(fs, Encoding.GetEncoding(encoding)))\n                {\n                    var json = new JsonReader(reader);\n\n                    var source = json.DeserializeArray()\n                        .Select(x => x.AsDocument);\n\n                    // read documents inside file and return one-by-one\n                    foreach (var doc in source)\n                    {\n                        yield return doc;\n                    }\n                }\n            }","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/litedb-org/LiteDB/blob/f906a5f850678719e39a39a006cb66dcae563cfa/LiteDB/Engine/SystemCollections/SysFileJson.cs#L1-L36","documentation":"Thrown by SysFileJson.Input when reading JSON from $file_json and the 'filename' option is missing or not a string. Uses ${this.Name} so the message correctly shows $file_json. Occurs before the FileStream/JsonReader are opened.","triggerScenarios":"SELECT * FROM $file_json() with no filename, or $file_json({ encoding:'utf-8' }) without filename, or filename as a non-string.","commonSituations":"Using $file_json directly and omitting the filename; building options dynamically without the filename key.","solutions":["Pass the filename: $file_json('data.json') or { filename: 'data.json' }.","Prefer $file('data.json') for extension-based routing.","Validate the filename option is a string before executing."],"exampleFix":"// before\ndb.Execute(\"SELECT * FROM $file_json()\"); // throws\n\n// after\ndb.Execute(\"SELECT * FROM $file_json('data.json')\");","handlingStrategy":"validation","validationCode":"if (string.IsNullOrWhiteSpace(filename)) throw new ArgumentException(\"filename required\");\ndb.Execute($\"SELECT * FROM $file_json('{filename}')\");","typeGuard":null,"tryCatchPattern":"try { db.Execute($\"SELECT * FROM $file_json('{filename}')\"); }\ncatch (LiteException ex) when (ex.Message.Contains(\"requires string as 'filename'\")) {\n    // obtain filename and retry\n}","preventionTips":["Always pass a filename to $file_json.","Use $file('x.json') for extension-based routing."],"tags":["system-collections","json","file-import","validation"],"backgroundTag":null,"analyzedSha":"f906a5f850678719e39a39a006cb66dcae563cfa","analyzedAt":"2026-08-13T21:56:30.148Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}