{"record":{"id":"416ff45b7f3ac838","repo":"theonedev/onedev","slug":"text-query-is-too-general-term","errorCode":null,"errorMessage":"Text query is too general: ${term}","messagePattern":"Text query is too general: (.+?)","errorType":"validation","errorClass":"TooGeneralQueryException","httpStatus":406,"severity":"error","filePath":"server-core/src/main/java/io/onedev/server/search/code/query/TextQueryOption.java","lineNumber":209,"sourceCode":"\n\tpublic void applyConstraints(BooleanQuery.Builder builder) {\n\t\tPreconditions.checkNotNull(term);\n\t\t\n\t\tif (fileNames != null) {\n\t\t\tBooleanQuery.Builder subQueryBuilder = new BooleanQuery.Builder();\n\t\t\tfor (String pattern: Splitter.on(\",\").omitEmptyStrings().trimResults().split(fileNames.toLowerCase()))\n\t\t\t\tsubQueryBuilder.add(new WildcardQuery(new Term(BLOB_NAME.name(), pattern)), BooleanClause.Occur.SHOULD);\n\t\t\tBooleanQuery subQuery = subQueryBuilder.build();\n\t\t\tif (subQuery.clauses().size() != 0)\n\t\t\t\tbuilder.add(subQuery, BooleanClause.Occur.MUST);\n\t\t}\n\n\t\tif (regex)\n\t\t\tbuilder.add(new RegexLiterals(term).asNGramQuery(BLOB_TEXT.name(), NGRAM_SIZE), BooleanClause.Occur.MUST);\n\t\telse if (term.length() >= NGRAM_SIZE)\n\t\t\tbuilder.add(new NGramLuceneQuery(BLOB_TEXT.name(), term, NGRAM_SIZE), BooleanClause.Occur.MUST);\n\t\telse\n\t\t\tthrow new TooGeneralQueryException(\"Text query is too general: \" + term);\n\t}\n\n\t@Override\n\tpublic FormComponentPanel<? extends QueryOption> newOptionEditor(String componentId) {\n\t\treturn new TextQueryOptionEditor(componentId, Model.of(this));\n\t}\n\n\tpublic static class Match implements Serializable {\n\n\t\tprivate static final long serialVersionUID = 1L;\n\t\t\n\t\tprivate final String line;\n\t\t\n\t\tprivate final PlanarRange position;\n\t\t\n\t\tpublic Match(String line, PlanarRange position) {\n\t\t\tthis.line = line;\n\t\t\tthis.position = position;","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/search/code/query/TextQueryOption.java#L191-L227","documentation":"TextQueryOption.applyConstraints builds a Lucene n-gram query over blob text for code text search. Non-regex terms shorter than the index's NGRAM_SIZE cannot be represented in the n-gram index, so instead of silently returning no results, TooGeneralQueryException is thrown when term.length() < NGRAM_SIZE.","triggerScenarios":"Creating a TextQuery with a non-regex term shorter than NGRAM_SIZE (typically 3 characters, e.g. 'ab') and applying its constraints during code text search; also via the code search UI with a very short keyword.","commonSituations":"User searches for a 1-2 character string like 'if' or 'x' in code search; programmatic text search passing short user input; misunderstanding that short substrings are not indexed.","solutions":["Search for a term at least NGRAM_SIZE characters long, or use the regex option (regex=true) which extracts literals from the pattern.","Extend the search term with more context, e.g. 'if(' or surrounding identifier characters.","Catch TooGeneralQueryException in the search entry point and inform the user of the minimum term length."],"exampleFix":"// before\nnew TextQuery().withOption(new TextQueryOption(\"if\", false, false, true));\n// after\nnew TextQuery().withOption(new TextQueryOption(\"if(\", false, false, true));","handlingStrategy":"validation","validationCode":"if (!regex && term.length() < 3) // NGRAM_SIZE\n    throw new IllegalArgumentException(\"Text term must be at least 3 characters (or use regex)\");","typeGuard":"boolean isUsableTextTerm(String term, boolean regex, int ngramSize) {\n    return regex || (term != null && term.length() >= ngramSize);\n}","tryCatchPattern":"try {\n    query = new TextQuery().withOption(new TextQueryOption(term, regex, false, true));\n} catch (TooGeneralQueryException e) {\n    return Result.error(\"Term too short for text search: \" + term);\n}","preventionTips":["Enforce a minimum term length in search UIs","Prefer regex=true when short literal patterns are needed (literals still required)","Document that short substrings are not indexed by n-gram search"],"tags":["lucene","code-search","ngram"],"backgroundTag":"invalid-query-parameter","analyzedSha":"d44925c47c37992c828ea673a5f9620539bc3ff2","analyzedAt":"2026-09-06T07:18:27.995Z","contentChangedAt":"2026-09-06T07:18:27.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}