Oils Error Catalog, With Hints

This doc lists errors from Oils (both OSH and YSH), with hints to help you fix them.

Each error is associated with a code like OILS-ERR-42, a string that search engines should find.

Table of Contents
How to Contribute
To Preview this Doc
Parse Errors - Rejected Input
OILS-ERR-10
OILS-ERR-11
OILS-ERR-12
OILS-ERR-13
OILS-ERR-14
Runtime Errors - Traditional Shell
OILS-ERR-100
OILS-ERR-101
Runtime Errors - Oils and YSH
OILS-ERR-200
OILS-ERR-201
Appendix
Kinds of Errors from Oils
Contributors

How to Contribute

If you see an error that you don't understand:

  1. Ask a question on #oil-help on Zulip. What's the problem, and what's the solution?
  2. 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.
  3. Add a tagged section below, with hints and explanations.
  4. 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)

Related help topics:

OILS-ERR-11

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

Related help topics:

OILS-ERR-12

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

Related help topics:

OILS-ERR-13

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

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:

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)

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)

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)

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

  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]'

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)

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)

Appendix

Kinds of Errors from Oils

Contributors

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

Generated on Mon, 22 Jul 2024 06:36:28 +0000