Debugging & Common Mistakes

Every programmer runs into bugs. This page will help you understand Quill's error messages, use the built-in debugger, and avoid the most common pitfalls that trip up new and experienced Quill developers alike.

Reading Error Messages

Quill tries hard to give you helpful error messages. Instead of cryptic codes, you get a pointer to exactly where things went wrong, along with an explanation and often a suggestion for how to fix it.

Anatomy of an error message

Every Quill error has three parts:

1. Location — the file name and line number
2. Source context — the actual line of code with an underline showing the exact spot
3. Hint — a suggestion for how to fix the problem

Let's look at five real error examples you will encounter and learn to read each one.

1. Type mismatch

You have a variable that should hold a number, but you gave it a string:

count is 0
-- ... later in the code ...
count is "hello"

Error [TYPE_MISMATCH] in counter.quill:4

  4 |  count is "hello"
               ^^^^^^^
  Type mismatch: 'count' was declared as Number but
  you are assigning a String.

  Hint: Did you mean to assign a number? If you need
        a string, declare a new variable instead.

Fix

count is 0
-- ... later ...
count is 42
-- Or, if you need a separate string:
label is "hello"

2. Undefined variable

You used a name that hasn't been defined yet:

say greeting

Error [UNDEFINED] in hello.quill:1

  1 |  say greeting
           ^^^^^^^^
  'greeting' is not defined. You used this name but
  never assigned a value to it.

  Hint: Did you forget to write: greeting is "..."?
        Check for typos in the variable name.

Fix

greeting is "Hello, World!"
say greeting

3. Missing colon

You forgot the : at the end of a block statement:

if x is 5
  say "five!"

Error [SYNTAX] in check.quill:1

  1 |  if x is 5
                ^
  Expected ':' after condition. Block statements in
  Quill must end with a colon.

  Hint: Add a colon:  if x is 5:

Fix

if x is 5:
  say "five!"

4. Wrong indentation

You mixed tabs and spaces, or used an inconsistent indent:

to greet name:
  say "Hello, {name}!"
	say "Welcome!"  -- this line uses a tab!

Error [INDENT] in greet.quill:3

  2 |    say "Hello, {name}!"
  3 |  	 say "Welcome!"
         ^
  Inconsistent indentation. Line 2 uses spaces but
  line 3 uses a tab character.

  Hint: Use spaces consistently (2 or 4 spaces).
        Configure your editor to insert spaces when
        you press Tab.

Fix

to greet name:
  say "Hello, {name}!"
  say "Welcome!"

5. Import not found

The file you're trying to bring in doesn't exist:

bring "./helpers/math"

Error [IMPORT_NOT_FOUND] in app.quill:1

  1 |  bring "./helpers/math"
              ^^^^^^^^^^^^^^^^
  Could not find module './helpers/math'. Looked for:
    - ./helpers/math.quill
    - ./helpers/math/index.quill

  Hint: Check that the file exists and the path is
        correct. Paths are relative to the current file.

Fix

-- Make sure the file exists at ./helpers/math.quill
bring "./helpers/math"

-- Or check if the path should be different:
bring "./utils/math"

The Debugger

Quill ships with a built-in interactive debugger that lets you pause your program, step through code line by line, and inspect variables. It's one of the most powerful tools you have for finding bugs.

Starting the debugger

Run your file with the debug command instead of run:

quill debug app.quill

You'll see a prompt like this:

Quill Debugger v1.0
Loaded: app.quill (42 lines)
Paused at line 1.

(quill-debug) > _

Setting breakpoints

A breakpoint tells the debugger to pause when it reaches a specific line. Use the break command:

(quill-debug) > break 10
Breakpoint set at line 10.

(quill-debug) > break 25
Breakpoint set at line 25.

To see all your breakpoints:

(quill-debug) > breakpoints
  1: line 10 (app.quill)
  2: line 25 (app.quill)

To remove a breakpoint:

(quill-debug) > unbreak 10
Breakpoint at line 10 removed.

Stepping through code

Inspecting variables

While paused, you can look at the current values of any variable:

(quill-debug) > print count
count = 7 (Number)

(quill-debug) > print name
name = "Alice" (String)

(quill-debug) > print items
items = ["apple", "banana", "cherry"] (List of String)

To see every variable in the current scope at once, use locals:

(quill-debug) > locals
  count   = 7 (Number)
  name    = "Alice" (String)
  items   = ["apple", "banana", "cherry"] (List)
  total   = 0 (Number)

Viewing the call stack

When you're inside a function, the stack command shows you how you got there:

(quill-debug) > stack
  #0  calculateTotal (app.quill:18)
  #1  processOrder (app.quill:32)
  #2  main (app.quill:45)

This reads from top to bottom: you're currently in calculateTotal at line 18, which was called by processOrder at line 32, which was called from the top level at line 45.

Full walkthrough: finding a bug

Let's debug a function that's returning the wrong result. Here's a program that should calculate the average of a list of numbers, but it's giving the wrong answer:

-- average.quill
to average numbers:
  total is 0
  for each num in numbers:
    total is total + num
  give back total / numbers.length

scores are [80, 90, 100]
result is average(scores)
say "Average: {result}"
-- Expected: 90, but getting: 60 ... why?

Let's fire up the debugger and find out:

$ quill debug average.quill

Quill Debugger v1.0
Loaded: average.quill (10 lines)
Paused at line 1.

(quill-debug) > break 5
Breakpoint set at line 5.

(quill-debug) > continue
Hit breakpoint at line 5.

  4 |    for each num in numbers:
  5 | >   total is total + num
  6 |    give back total / numbers.length

(quill-debug) > print num
num = 80 (Number)

(quill-debug) > print total
total = 0 (Number)

(quill-debug) > step
  5 | >   total is total + num

(quill-debug) > print total
total = 80 (Number)

(quill-debug) > continue
Hit breakpoint at line 5.

(quill-debug) > print num
num = 90 (Number)

(quill-debug) > print total
total = 80 (Number)

(quill-debug) > step

(quill-debug) > print total
total = 170 (Number)

(quill-debug) > continue
Hit breakpoint at line 5.

(quill-debug) > print num
num = 100 (Number)

(quill-debug) > step

(quill-debug) > print total
total = 270 (Number)

(quill-debug) > print numbers.length
numbers.length = 3 (Number)

-- Aha! 270 / 3 = 90. That's correct!
-- Let's continue to see the final output...

(quill-debug) > continue
Average: 90
Program finished.

Common Mistakes & Fixes

Here are the most common mistakes Quill programmers make. Don't feel bad if you run into these — everyone does, especially when learning a new language. Each entry shows the wrong code, the error you'll see, why it's wrong, and how to fix it.

name "hello"

Error [SYNTAX] in app.quill:1

  1 |  name "hello"
            ^^^^^^^
  Unexpected string literal. Did you mean to assign
  this value to 'name'?

  Hint: Use 'is' for assignment:  name is "hello"

name is "hello"

count = 10

Error [SYNTAX] in app.quill:1

  1 |  count = 10
              ^
  Unexpected character '='. Quill uses 'is' for
  assignment, not '='.

  Hint: Write:  count is 10

count is 10

if x is 5
  say "five!"

Error [SYNTAX] in app.quill:1

  1 |  if x is 5
                ^
  Expected ':' after condition.

  Hint: Add a colon:  if x is 5:

if x is 5:
  say "five!"

to greet name:
  say "Hello, {name}!"
say "Welcome aboard!"   -- oops, this is outside the function!

to greet name:
  say "Hello, {name}!"
  say "Welcome aboard!"   -- now inside the function

to add a, b:
  return a + b

Error [UNDEFINED] in math.quill:2

  2 |    return a + b
         ^^^^^^
  'return' is not defined. Did you mean 'give back'?

  Hint: Quill uses 'give back' to return values:
        give back a + b

to add a, b:
  give back a + b

if name == "Alice":
  say "Hi Alice!"

Error [SYNTAX] in app.quill:1

  1 |  if name == "Alice":
               ^^
  Unexpected '=='. Quill uses 'is' for comparison.

  Hint: Write:  if name is "Alice":

if name is "Alice":
  say "Hi Alice!"

to fetchUser:
  response is await fetch("https://api.example.com/user")
  give back response.json()

-- Calling without await:
user is fetchUser()
say user.name   -- undefined! user is a Promise, not the data

user is await fetchUser()
say user.name   -- works! "Alice"

numbers are [1, 2, 3, 4, 5]

for each num in numbers:
  if num is 3:
    numbers.remove(num)   -- modifying the list mid-loop!

say numbers
-- Expected: [1, 2, 4, 5]
-- Actual:   [1, 2, 4] ... it skipped 4!

numbers are [1, 2, 3, 4, 5]

-- Build a new list instead of modifying the original:
filtered is numbers.filter(to (num): num is not 3)

say filtered
-- [1, 2, 4, 5]

count is 5
say "Count: " + count

Error [TYPE_MISMATCH] in app.quill:2

  2 |  say "Count: " + count
                     ^
  Cannot use '+' with String and Number.

  Hint: Use string interpolation instead:
        say "Count: {count}"

count is 5
say "Count: {count}"

-- At the top level of a file:
my.name is "Alice"

Error [CONTEXT] in app.quill:1

  1 |  my.name is "Alice"
       ^^
  'my' can only be used inside a 'describe' block.
  It refers to the current instance of a class.

  Hint: If you want a plain variable, just write:
        name is "Alice"

-- For a plain variable:
name is "Alice"

-- Or inside a class:
describe Person:
  to setup name:
    my.name is name   -- correct: inside a describe block

describe Dog:
  to setup name:
    my.name is name

-- Missing 'new':
buddy is Dog("Buddy")

Error [CALL] in app.quill:6

  6 |  buddy is Dog("Buddy")
                ^^^
  'Dog' is a class, not a function. Use 'new' to
  create an instance.

  Hint: Write:  buddy is new Dog("Buddy")

buddy is new Dog("Buddy")
say buddy.name   -- "Buddy"

-- fileA.quill
bring "./fileB"

to helperA:
  say "A"

-- fileB.quill
bring "./fileA"   -- circular!

to helperB:
  say "B"

Error [CIRCULAR_IMPORT] in fileB.quill:1

  Circular dependency detected:
    fileA.quill -> fileB.quill -> fileA.quill

  Hint: Move shared code into a third file that both
        can import, or restructure to remove the cycle.

-- shared.quill (new file with shared code)
to sharedHelper:
  say "shared"

-- fileA.quill
bring "./shared"

-- fileB.quill
bring "./shared"

numbers is range(1, 5)
say numbers
-- You expected: [1, 2, 3, 4, 5]
-- You got:      [1, 2, 3, 4]

-- To include 5, go one higher:
numbers is range(1, 6)
say numbers
-- [1, 2, 3, 4, 5]

urls are ["https://api.com/1", "https://api.com/2", "https://api.com/3"]

for each url in urls:
  response is await fetch(url)   -- waits for each one before starting the next
  say response.status

urls are ["https://api.com/1", "https://api.com/2", "https://api.com/3"]

-- Fire all requests at the same time:
promises are urls.map(to (url): fetch(url))
responses is await Promise.all(promises)

for each response in responses:
  say response.status

component Counter:
  count is state(0)

  to increment:
    count is count + 1   -- directly modifying! UI won't update

  to render:
    give back <button on click is increment>
      "{count}"
    </button>

component Counter:
  [count, setCount] is state(0)

  to increment:
    setCount(count + 1)   -- use the setter! UI will update

  to render:
    give back <button on click is increment>
      "{count}"
    </button>

to findUser id:
  for each user in users:
    if user.id is id:
      give back user
  -- what if the user isn't found? gives back nothing!

result is findUser(999)
say result.name   -- Error: Cannot read 'name' of nothing

to findUser id:
  for each user in users:
    if user.id is id:
      give back user
  give back nothing   -- explicit!

result is findUser(999)
if result is not nothing:
  say result.name
otherwise:
  say "User not found"

total is 0

to addToTotal amount:
  total is amount   -- this creates a NEW local 'total', doesn't modify the outer one!

addToTotal(10)
addToTotal(20)
say total   -- still 0!

total is 0

to addToTotal amount:
  change total to total + amount   -- explicitly modify the outer variable

addToTotal(10)
addToTotal(20)
say total   -- 30

to greet firstName, lastName:
  say "Hello, {firstName} {lastName}!"

-- Too few arguments:
greet("Alice")

Error [ARGS] in app.quill:5

  5 |  greet("Alice")
       ^^^^^
  'greet' expects 2 arguments (firstName, lastName)
  but was called with 1.

  Hint: Add the missing argument:
        greet("Alice", "Smith")

greet("Alice", "Smith")

-- Or make the parameter optional with a default value:
to greet firstName, lastName is "":
  if lastName is "":
    say "Hello, {firstName}!"
  otherwise:
    say "Hello, {firstName} {lastName}!"

if score > 90:
  grade is "A"
otherwise:
  grade is "F"
otherwise if score > 80:   -- this will never run!
  grade is "B"

Error [SYNTAX] in grades.quill:5

  5 |  otherwise if score > 80:
       ^^^^^^^^^
  'otherwise if' cannot appear after 'otherwise'.
  The 'otherwise' block must be last.

  Hint: Move 'otherwise if' branches before 'otherwise'.

if score > 90:
  grade is "A"
otherwise if score > 80:
  grade is "B"
otherwise:
  grade is "F"

Debugging Strategies

Beyond the debugger and error messages, here are proven strategies for tracking down bugs efficiently.

Print debugging with say

The simplest and often most effective technique. Drop say statements into your code to trace what values variables have at different points.

to processOrder items:
  say "[DEBUG] processOrder called with {items.length} items"
  total is 0
  for each item in items:
    say "[DEBUG] item: {item.name}, price: {item.price}"
    total is total + item.price
  say "[DEBUG] total before tax: {total}"
  give back total * 1.08

Divide and conquer

When you have a big program and something is wrong, comment out half the code. If the bug disappears, it's in the half you commented out. If the bug remains, it's in the other half. Keep halving until you find it.

-- Comment out sections to isolate the bug:

-- step1()
-- step2()
step3()        -- bug appears? it's in step3
-- step4()

This is especially useful for logic bugs that don't produce error messages.

Rubber duck debugging

Explain your code out loud, line by line, to anyone (or anything — a rubber duck works). The act of explaining often reveals the mistake because you have to think about what each line actually does, not what you assume it does.

Reading the compiled JavaScript

Since Quill compiles to JavaScript, you can inspect the output to understand what's actually running:

# Generate the JS output
quill build app.quill

# Read it
cat app.js

This is particularly helpful for understanding how Quill's syntactic sugar translates to actual operations. If the compiled JS looks wrong, you've found a compiler bug (rare, but possible) or a misunderstanding of Quill syntax.

Using the type checker

Quill's check command analyzes your code without running it and catches many errors before they become runtime bugs:

quill check app.quill

app.quill:14  Warning: 'result' might be nothing here.
                        Add a check before accessing .name
app.quill:22  Error:   Cannot call 'push' on a String.
                        Did you mean to use a List?

Found 1 error and 1 warning.

Run quill check early and often. Many developers add it to their editor's save hook so every file is checked automatically.

Using tests to prevent regressions

Once you've fixed a bug, write a test that would have caught it. This prevents the same bug from coming back.

-- test_average.quill
bring "./average"

test "average of three numbers":
  result is average([80, 90, 100])
  expect result to be 90

test "average of empty list":
  result is average([])
  expect result to be 0

test "average of one number":
  result is average([42])
  expect result to be 42

quill test test_average.quill

See the Testing docs for more on writing and running tests.

Check your assumptions

Most bugs come from wrong assumptions. Before diving deep, verify the basics:

• Is the function even being called? Add a say "HERE" at the top of the function.
• Is the data what you think it is? Print the variable right before the line that's failing.
• Are you editing the right file? It sounds silly, but it happens. Add a unique say statement to confirm.
• Did you save the file? Some editors don't auto-save. Make sure your changes are on disk before running.

Minimal reproducible example

When a bug is hard to find, try to create the smallest possible program that still shows the problem. Start with your full program and remove things one by one until you have the bare minimum that triggers the bug.

-- Start: 200-line program with a bug
-- Step 1: Remove unrelated functions  (150 lines)
-- Step 2: Hardcode inputs              (80 lines)
-- Step 3: Remove UI code               (30 lines)
-- Step 4: Simplify the data            (10 lines)
-- Now you can see the bug clearly!

Compare with working code

If something used to work and now it doesn't, use version control to compare:

# See what changed since the last working version
git diff HEAD~3 app.quill

# Or check out the old version temporarily
git stash
quill run app.quill   -- does the old version work?
git stash pop

Often the bug is in something you changed recently. Narrowing down which change broke things is half the battle.

Getting Help

Stuck on something? Here's where to look, in order:

1. Check the error message hints

Quill's error messages almost always include a hint. Read it carefully — it often tells you exactly what to do.

2. Search the docs

The documentation pages cover every part of the language. The Language Reference is especially useful when you're unsure about syntax, and the Standard Library docs list every built-in function.

3. Try the playground

The online playground lets you test small code snippets instantly without setting anything up. It's a great way to verify how a feature works in isolation.

4. Ask on Discord

The Quill community on Discord is active and welcoming. Post your question in the #help channel with:

• The code you're trying to run
• The full error message (or unexpected output)
• What you expected to happen

5. Check the examples directory

The examples directory contains dozens of working programs. If you're trying to do something specific, there's probably an example that shows how. Seeing working code is often more helpful than reading explanations.

Next steps

• Read the Language Reference for a full overview of Quill syntax
• Explore the Standard Library to learn about built-in functions
• Learn about Testing to prevent bugs proactively
• Try the Playground to experiment risk-free
• Check out Examples for working reference code