Ask a question on #oil-help on Zulip. What's the problem, and what's the solution?
Then grep the source code for the confusing error message. Tag it with a string like OILS-ERR-43, picking a new number according to the conventions below.
Add a tagged section below, with hints and explanations.
- Quote the error message. You may want copy and paste from the output of test/{parse,runtime,ysh-parse,ysh-runtime}-errors.sh. Add an HTML comment  about that.
- Link to relevant sections in the Oils Reference.
Optionally, add your name to the acknowledgements list at the end of this doc.

Note that error messages are hard to write, because a single error could result from many different user intentions!

To Preview this Doc

Right now I use this command:

build/doc.sh split-and-render doc/error-catalog.md

Then paste this into your browser:

file:///home/andy/git/oilshell/oil/_release/VERSION/doc/error-catalog.html

(Replace with your home dir)

Parse Errors - Rejected Input

Roughly speaking, a parse error means that text input was rejected, so the shell didn't try to do anything.

Examples:

echo )   # Shell syntax error

type -z  # -z flag not accepted

These error codes start at 10.

OILS-ERR-10

      setvar x = true
             ^
[ -c flag ]:3: setvar couldn't find matching 'var x' (OILS-ERR-10)

Did you forget to declare the name with the var keyword?
Did you mean to use the setglobal keyword?

OILS-ERR-11

  echo $'\z'
         ^
[ -c flag ]:1: Invalid char escape in C-style string literal (OILS-ERR-11)

Did you mean $'\\z'? Backslashes must be escaped in $'' and u'' and b'' strings.
Did you mean something like $'\n'? Only valid escapes are accepted in YSH.

OILS-ERR-12

  echo "\z"
        ^
[ -c flag ]:1: Invalid char escape in double quoted string (OILS-ERR-12)

Did you mean "\\z"? Backslashes must be escaped in double-quoted strings.
Did you mean something like "\$"? Only valid escapes are accepted in YSH.

OILS-ERR-13

  echo \z
       ^~
[ -c flag ]:1: Invalid char escape in unquoted word (OILS-ERR-13)

Did you mean \\z? Backslashes must be escaped in unquoted words.
Did you mean something like \$? Only valid escapes are accepted in YSH.

OILS-ERR-14

  if ((1 > 0 && 43 > 42)); then echo yes; fi
     ^~
[ -c flag ]:1: Bash (( not allowed in YSH (parse_dparen, see OILS-ERR-14 for wart)

Two likely causes:

Do you need to rewrite bash arithmetic as YSH arithmetic (which is Python-like)?
Do you need to work around an unfortunate wart in YSH?

Examples:

if (1 > 0 and 43 > 42) {  # YSH-style
  echo yes
}

if ( (x + 1) < n) {  # space between ( ( avoids ((
  echo yes
}

Runtime Errors - Traditional Shell

These errors may occur in shells like bash and zsh.

They're numbered starting from 100. (If we have more than 90 parse errors, we can start a new section, like 300.)

OILS-ERR-100

  findz
  ^~~~~
[ -c flag ]:1: 'findz' not found (OILS-ERR-100)

Did you misspell a command name?
Did you misspell a shell function or a YSH proc?
Is the file in your $PATH? The PATH variable is a colon-separated list of directories, where executable files may live.
Is findz file executable bit set? (chmod +x)

OILS-ERR-101

Let's look at three instances of this error.

  declare -A assoc; assoc[x]=1
                    ^~~~~~
[ -c flag ]:1: fatal: Assoc array keys must be strings: $x 'x' "$x" etc. (OILS-ERR-101)

Is x a string? Then add quotes: assoc['x']=1
Is x a variable? Then write: assoc[$x]=1

Same idea here:

  declare -A assoc; echo ${assoc[x]}
                                 ^
[ -c flag ]:1: fatal: Assoc array keys must be strings: $x 'x' "$x" etc. (OILS-ERR-101)

Is x a string? Then add quotes: ${assoc['x']}
Is x a variable? Then write: ${assoc[$x]}

The third example is tricky because unset takes a string. There's an extra level of parsing, which:

Implies an extra level of quoting
Causes OSH to display the following nested error message

  assoc[k]
       ^
[ dynamic LHS word at line 1 of [ -c flag ] ]:1

  declare -A assoc; key=k; unset "assoc[$key]"
                                 ^
[ -c flag ]:1: fatal: Assoc array keys must be strings: $x 'x' "$x" etc. (OILS-ERR-101)

To fix it, consider using single quotes:

unset 'assoc[$key]'

This is the error in Parsing Bash is Undecidable (2016)
Also mentioned in Known Differences

Runtime Errors - Oils and YSH

These errors don't occur in shells like bash and zsh.

They may involve Python-like expressions and typed data.

They're numbered starting from 200.

OILS-ERR-200

  cat ("myfile")
      ^
[ -c flag ]:1: fatal: 'cat' appears to be external. External commands don't accept typed args (OILS-ERR-200)

Builtin commands and user-defined procs may accept typed args, but external commands never do.
Did you misspell a YSH proc? If a name is not found, YSH assumes it's an external command.
Did you forget to source a file that contains the proc or shell function you wanted to run?

OILS-ERR-201

  = "age: " + "100"
            ^
[ -c flag ]:1: fatal: Binary operator expected numbers, got Str and Str (OILS-ERR-201)

  = 100 + myvar
        ^
[ -c flag ]:2: fatal: Binary operator expected numbers, got Int and Str (OILS-ERR-201)

Did you mean to use ++ to concatenate strings/lists?
The arithmetic operators can coerce string operands to numbers. However, if you are operating on user provided input, it may be a better idea to first parse that input with int() or float().

OILS-ERR-202

  pp (42.0 === x)
                ^~~
[ -c flag ]:3: fatal: Equality isn't defined on Float values (OILS-ERR-202)

Floating point numbers shouldn't be tested for equality. Alternatives:

= abs(42.0 - x) < 0.1
= floatEquals(42.0, x)

Appendix

Kinds of Errors from Oils

Runtime errors (status 1) - the shell tried to do something, but failed.
- Example: echo hi > /does/not/exist
Parse errors and builtin usage errors (status 2) - input rejected, so the shell didn't try to do anything.
Uncaught I/O errors (status 2)
Expression errors (status 3)
User errors from the error builtin (status 10 is default)

Contributors

(If you updated this doc, feel free to add your name to the end of this list.)

Generated on Tue, 06 Aug 2024 16:19:56 +0000