{"record":{"id":"9dd9aefcbd7c0a34","repo":"iOfficeAI/OfficeCLI","slug":"not-found","errorCode":"not_found","errorMessage":"row[col op val] found no usable table on {scope}: a header '{h.name}' exists at {h.sheet}!{h.cellRef}, but the surrounding cells are not a recognizable table. Auto-detection needs at least 2 adjacent non-empty header columns and at least 1 data row; a blank-header column in the middle or a header-only block breaks it. Create the table explicitly (add /{h.sheet} --type table --prop ref=), or address cells directly.","messagePattern":"row\\[col op val\\] found no usable table on (.+?): a header '(.+?)' exists at (.+?)!(.+?), but the surrounding cells are not a recognizable table\\. Auto-detection needs at least 2 adjacent non-empty header columns and at least 1 data row; a blank-header column in the middle or a header-only block breaks it\\. Create the table explicitly \\(add /(.+?) --type table --prop ref=\\), or address cells directly\\.","errorType":"exception","errorClass":"CliException","httpStatus":null,"severity":"error","filePath":"src/officecli/Handlers/Excel/ExcelHandler.Query.RowWhere.cs","lineNumber":145,"sourceCode":" }\n\n var candidates = listObjCands.Count > 0 ? listObjCands : detectedCands;\n\n if (candidates.Count == 0)\n {\n var cols = string.Join(\", \", colConds.Select(c => $\"'{StripColPrefix(c.Key)}'\"));\n var scope = sheetFilter == null ? \"any sheet\" : $\"sheet '{sheetFilter}'\";\n // If NO table structure exists in scope at all, but the column NAME\n // literally exists as a cell, the honest cause is \"not a recognizable\n // table\" (a blank-header gap column, or a header-only block with no\n // data rows) — point at explicit table creation. Guard on an empty\n // scopeTables: when a real table WAS detected but simply doesn't own\n // one of a compound predicate's columns (`row[Region=X and Bonus>1]`\n // where Bonus is absent), fall through to BuildNoColumnException so\n // the error names the missing column and lists the available ones,\n // instead of wrongly blaming a valid column's surrounding cells.\n if (scopeTables.Count == 0 && FindHeaderLikeCell(sheetFilter, colConds) is {} h)\n throw new Core.CliException(\n $\"row[col op val] found no usable table on {scope}: a header '{h.name}' exists at \" +\n $\"{h.sheet}!{h.cellRef}, but the surrounding cells are not a recognizable table. \" +\n \"Auto-detection needs at least 2 adjacent non-empty header columns and at least 1 data \" +\n \"row; a blank-header column in the middle or a header-only block breaks it. Create the \" +\n $\"table explicitly (add /{h.sheet} --type table --prop ref=), or address cells directly.\")\n {\n Code = \"not_found\",\n Suggestion = $\"add /{h.sheet} --type table --prop ref=\",\n };\n throw BuildNoColumnException(\n $\"row[col op val] found no table on {scope} with column(s) {cols}. \" +\n \"Column predicates resolve header names (or column letters) against a ListObject or a detected (header-row) table.\",\n scopeTables, colConds);\n }\n if (candidates.Count > 1)\n {\n var where = string.Join(\", \", candidates.Select(c => $\"{c.sheetName}!{c.label}\"));\n var sheets = candidates.Select(c => c.sheetName).Distinct().ToList();","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Handlers/Excel/ExcelHandler.Query.RowWhere.cs#L127-L163","documentation":"Thrown by QueryRowsByColumnPredicate when no recognizable table was found in scope, but the predicate's column name DOES exist as a bare cell. This means the data is not structured as a detectable table: auto-detection requires at least 2 adjacent non-empty header columns and at least 1 data row. A blank-header gap column or a header-only block breaks detection.","triggerScenarios":"Running row[Region=X] against a sheet where 'Region' is a single header cell with no adjacent populated headers, or where a blank column splits the header row, or where headers exist but there are no data rows beneath them.","commonSituations":"Importing a CSV whose first column header is blank; pasting a header-only block; a header row interrupted by a merged/empty cell; data laid out as a key/value block instead of a tabular table.","solutions":["Create the table explicitly so column names are stored metadata: add /SheetName --type table --prop ref= covering the header and data rows.","If the layout is correct but detection is being defeated by a blank header, fill the blank header or remove the gap column.","If you only need cells, address them directly (e.g. /Sheet1/B2) instead of using row[...]."],"exampleFix":"// before (header 'Region' sits alone or next to a blank cell)\nget /Sheet1/row[Region='West']\n\n// after (declare the table range explicitly)\nadd /file.xlsx /Sheet1 --type table --prop ref=A1:D100\nget /Sheet1/row[Region='West']","handlingStrategy":"validation","validationCode":"// Ensure the target range is a real ListObject before relying on row[...].\nbool HasTableCovering(ExcelHandler excel, string sheet, string rangeRef)\n => excel.Get($\"/{sheet}\").Children.Any(c => c.Type == \"table\" && (c.Format.TryGetValue(\"ref\", out var r) && r?.ToString() == rangeRef));","typeGuard":null,"tryCatchPattern":"try { var rows = excel.QueryRowsByColumnPredicate(sheet, expr); }\ncatch (Core.CliException ex) when (ex.Code == \"not_found\" && ex.Message.Contains(\"not a recognizable table\"))\n{ /* prompt user to add --type table with an explicit ref */ }","preventionTips":["Declare tables explicitly (add --type table --prop ref=A1:D100) rather than relying on header-sniff detection.","Ensure header rows have no blank gap columns and at least one data row.","Address cells directly when the data is not tabular."],"tags":["excel","row-where","table-detection","validation"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}