# Atlas grep tool: "pattern is required" and how to fix it > To fix "pattern is required" in Atlas grep, supply a non-empty `pattern`. It is a regex, not a plain substring, so escape metacharacters when matching literals. Atlas grep fails with "pattern is required" because GrepTool validates params.pattern before asking for permission or touching the filesystem, so an empty pattern never reaches ripgrep. The fix is to supply a non-empty `pattern`, and to remember that it is a regex, not a plain substring. Use `include` to scope by file glob and `path` to scope by directory rather than leaving the pattern blank and hoping the other parameters do the filtering. If what you actually want is to list files by name rather than search their contents, use glob instead of grep, and escape regex metacharacters when you are searching for literal braces or parentheses. ## Symptom The grep tool fails with: pattern is required. The call stops immediately, before any permission prompt and before ripgrep is invoked, so no files are searched. ## Cause Atlas's GrepTool validates params.pattern before asking for permission or touching the filesystem, so an empty pattern never reaches ripgrep. The pattern parameter was missing or empty in the call, which means there was nothing to search for. ## Fix 1. Supply a non-empty `pattern`. It is a regex, not a plain substring, so a bare word matches as a regex that happens to have no metacharacters. 2. Use `include` to scope by file glob and `path` to scope by directory, instead of leaving the pattern blank and expecting the scope parameters to do the work. 3. If you want to list files by name rather than content, use glob instead of grep. 4. Escape regex metacharacters when searching for literal braces or parentheses, since an unescaped metacharacter changes what the pattern matches. 5. Re-run grep and confirm it returns matching lines rather than the pattern is required error. ## Why does Atlas grep say "pattern is required" Atlas grep says "pattern is required" because GrepTool validates params.pattern before asking for permission or touching the filesystem. An empty pattern never reaches ripgrep, so the call fails immediately with no permission prompt and 0 files searched. The validation order is the interesting part. GrepTool checks the pattern first, ahead of the permission gate and ahead of any filesystem access, which means a malformed call is rejected at the cheapest possible point. Nothing is read, nothing is prompted, and nothing changes on your machine. That ordering also explains why the error looks so abrupt: there is no partial output to inspect and no permission dialog to dismiss, just a single line saying the pattern is missing. An empty pattern is not a search that matches everything, it is not a search at all, and Atlas declines to guess what you meant by it. ## How to write a valid pattern for Atlas grep Supply a non-empty `pattern` to Atlas grep, and treat it as a regex rather than a plain substring. A word like handleRequest works because it contains 0 metacharacters, but a pattern with braces, parentheses, dots, or pipes is interpreted as regex syntax and will not match those characters literally. The regex semantics are the second most common source of surprise on this tool, right after the missing pattern itself. Searching for a function call by typing its name with parentheses matches a group, not a literal call. Searching for a dotted property matches any character where you meant a period. Escape regex metacharacters when searching for literal braces or parentheses, and the pattern does what you expected. When you want a broad match, the regex power is an advantage: an alternation finds several spellings of a symbol in one pass, which no substring search can do. The point is to know which mode you are in. ## How to scope an Atlas grep search with include and path Scope an Atlas grep search with 2 parameters: use `include` to scope by file glob and `path` to scope by directory. Those are the correct places to narrow a search, and neither one substitutes for the required `pattern`, which is what grep actually matches against. People sometimes reach for a blank pattern precisely because they are thinking in terms of scope rather than content: they want everything in one directory, or every file of one kind. Grep is not the tool for that, and leaving the pattern empty does not turn it into one. Use `include` and `path` alongside a real pattern to answer questions like where a symbol appears within one package, or which config files mention a given key. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so a tightly scoped grep is also a smaller permission ask than a repository-wide one. ## Should I use Atlas grep or glob Use Atlas grep to search file contents and glob to list files by name. Those are 2 different questions. If you want to list files by name rather than content, use glob instead of grep, because an empty pattern in grep just produces the pattern is required error. The two tools answer different questions and confusing them is the most common way to end up with an empty pattern. Grep asks: which lines in which files say this. Glob asks: which files are called this. If you are hunting for a symbol, an error string, a config key, or a call site, grep is right and the pattern is the symbol. If you are hunting for a file whose name you half remember, glob is right and the pattern is a filename glob. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so between grep, glob, and semantic search, there is a tool matched to each shape of question. ## How to verify the Atlas grep pattern fix worked Verify the Atlas grep fix by re-running the call. A non-empty pattern passes GrepTool's validation, the permission check runs, and ripgrep returns matching lines. The absence of "pattern is required" means the pattern parameter reached the tool with at least 1 character in it. Getting past validation is not the same as getting the results you wanted, so check the output too. A valid pattern that returns nothing means grep searched and found no matches, which is a real answer and often a useful one, but it can also mean the regex is matching something other than what you intended. If you searched for a literal with metacharacters in it and got zero hits, escape the metacharacters and try again before concluding the code is not there. If you scoped with `include` or `path` and got nothing, widen the scope one step and see whether the matches were simply outside the boundary you drew. ## FAQ ### what does pattern is required mean in Atlas grep Atlas's GrepTool validates params.pattern before asking for permission or touching the filesystem, so an empty pattern never reaches ripgrep. The message means the pattern parameter was missing or empty. ### is the Atlas grep pattern a regex or a substring It is a regex, not a plain substring. A word with no metacharacters behaves like a substring, but braces, parentheses, dots, and pipes are interpreted as regex syntax. ### how do I search for a literal parenthesis in Atlas grep Escape regex metacharacters when searching for literal braces or parentheses. Unescaped, they are read as regex syntax and will not match the characters themselves. ### how do I limit an Atlas grep search to one folder Use `path` to scope by directory, and `include` to scope by file glob. Both work alongside a non-empty `pattern`, which is still required. ### can I use Atlas grep to list files by name No. If you want to list files by name rather than content, use glob instead of grep. Leaving grep's pattern empty to list files just produces the pattern is required error. ### does Atlas grep ask for permission before searching Yes, but the pattern check comes first. GrepTool validates params.pattern before asking for permission or touching the filesystem, so an empty pattern fails before any prompt appears. ### why does my valid Atlas grep pattern return no matches Either the code genuinely does not contain it, or the regex is matching something other than what you meant. Escape metacharacters, or widen the `include` and `path` scope, and search again. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/grep-pattern-required Source of truth: aeo_pages row `/resources/troubleshooting/grep-pattern-required` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.