Debugging without guessing.

Start with five quiet checks.

Most early issues are a typo, the wrong folder, or using a feature from the reference runtime with the small native alpha. Work from the smallest check to the largest—not from guesses.

1. Confirm the command exists: reflex --version.
2. Confirm you are in the folder containing the file: list the files and check the spelling.
3. Validate without running: reflex check hello.rflx.
4. Run the same file: reflex run hello.rflx.
5. Read the filename, line, column, and message in the error before changing code.

CLI and file problems

Read an error before you edit.

A native CLI error is designed to start with a location. Treat it like a coordinate, not a verdict. In a message shaped like app.rflx:12:5: expected ':' before block, app.rflx is the file, 12 is the line, 5 is the column, and the final phrase is the immediate parser expectation.

1. Open the named file and line.
2. Read the line above it too; a missing closing quote, delimiter, or colon often changes what the next line means.
3. Fix the first error only.
4. Run reflex check again. A later error may disappear once the parser can understand the earlier section.

Syntax and indentation

reflex check is the fastest tool for syntax. It does not execute the program, so it is safe to use repeatedly while you edit.

# broken.rflx
if true:
print("This needs spaces")

# fixed.rflx
if true:
    print("This is inside the block")

The error location uses filename:line:column. Fix the first reported syntax error, then run check again—later messages may be consequences of the first one.

Runtime errors: ask what value you have.

When syntax is valid but run fails, isolate the expression on the reported line. Most runtime errors describe a mismatch between the operation and the value it received.

Add temporary print() statements just before the failing expression. Print the incoming value, a list’s .length, and the branch you expect to run. Remove the prints once the behavior is understood.

When it runs but gives the wrong answer.

A program can be syntactically valid and still be wrong. Start by writing one concrete input and the exact result you expect. Then make the program show its intermediate values at the boundary where the result becomes surprising.

# range ends before its final number
numbers = range(1, 5)
print(numbers.join(", "))  # 1, 2, 3, 4

# Include 5 by choosing an end of 6.
with_five = range(1, 6)
print(with_five.join(", "))

Do not hide a behavior bug with a broad condition. State the invariant in code where possible: check an input is non-empty before taking its first item, or calculate a named is_valid value before using it in multiple branches.

Find where a value changed—or never existed.

For a failing function, print the arguments at entry, print the computed local value, and print just before return. This tells you whether the bug is in the caller, the function’s calculation, or the code that uses the returned result.

discount(price, percent = 0):
    print(`price: ${price}`)
    print(`percent: ${percent}`)
    amount = price * percent / 100
    print(`discount: ${amount}`)
    return amount

print(discount(80, 25))

Remember that an indented block has a local scope. If a value is intended to be used after an if or loop, initialize it outside the block and assign to it deliberately. If a name is only meaningful inside the branch that created it, use it there rather than making its lifetime unclear.

Reduce, check, observe, change one thing.

1. Reduce: make a new tiny repro.rflx containing only the failing behavior.
2. Check: run reflex check repro.rflx.
3. Observe: use targeted print() calls; write down expected output and actual output.
4. Change one thing: alter one expression, rerun, and keep notes. Avoid fixing five things at once.
5. Lock in the repair: keep the small reproduction so it can become a regression test later.

# repro.rflx — keep it small
names = ["Ada"]
print(names.first())

Inspect data without guessing.

Use templates for readable debug output: print(`count: ${items.length}`). For a list, print its joined form and its length. For a branch, print a marker immediately inside each branch. For a function, print arguments at its entry and its return value just before returning.

items = ["one", "two"]
print(`items: ${items.join(" | ")}`)
print(`count: ${items.length}`)

if items.includes("two"):
    print("found two")
else:
    print("two is missing")

Keep messages concrete. “entered save branch” is better than “here”; request id: … is better than printing a whole unrelated structure. Remove or gate temporary logging before sharing output that could contain private data.

Turn a repair into a small safety net.

After repairing a bug, keep the smallest example that would have caught it. You do not need a heavy framework to get value from this habit. A folder of small .rflx examples and expected terminal output creates a practical early regression suite.

1. Save the minimized failing program with a descriptive name, such as range-end-is-exclusive.rflx.
2. Add a comment with the expected output or behavior.
3. Run reflex check and reflex run after changes to the runtime or the program.
4. When a behavior is intentionally changed, update the example and explain why.

# expected output: 2, 4, 6
numbers = range(1, 7)
even = numbers.filter(fun(n) => n % 2 == 0)
print(even.join(", "))

When you share a repair, include the version, command, input, and result. “Fixed the range bug” is not enough; “range(1, 7) now produces the expected end-exclusive sequence in Reflex 0.1.0-alpha.1” is checkable.

Separate a language defect from an install or platform issue.

Before changing source code, identify which layer failed:

The real downloadable artifact today is the tested Debian/Ubuntu Linux package. Windows and macOS packages are not marked as available until genuine outputs exist. A platform-specific installer problem should be reported with the package version and operating-system details, not misdiagnosed as a language syntax issue.

Web and desktop diagnosis

Web routes, CSS loading, desktop WebViews, and web()/native() belong to the Python reference runtime today. First verify which runtime you are using. An installed standalone CLI reporting an unknown builtin for web is an expected scope boundary, not a syntax bug.

• For a web route, print request.method and request.path in middleware.
• For CSS, confirm the path is next to the program as expected; prefer a tiny inline style while isolating a load issue.
• For generated desktop output, open the generated index.html first. Then separately test the optional pywebview launcher.
• Do not expose a development server or desktop bridge to untrusted input without reviewing the security boundary.

Bridge worker failures

A bridge crosses a process boundary. Test both sides independently: run the foreign-language worker with a sample JSON request, then run the Reflex call. Confirm the external runtime exists (node, lua, dotnet, and so on), the target path is correct, and the worker prints one valid JSON response.

Write a report someone can act on.

If a minimal program still behaves incorrectly, include these items in the report:

1. Reflex version from reflex --version and the operating system.
2. The smallest complete .rflx file that fails.
3. The exact command you ran.
4. Actual output/error and what you expected instead.
5. Whether reflex check passes.
6. For reference-runtime features, the runtime/dependency versions and any worker program involved.

Remove passwords, tokens, personal paths, and private source before sending it. A report that is precise, small, and safe can become a regression test.

Know when the missing feature is the answer.

The 0.1 standalone runtime deliberately does not yet promise modules, package installation, network/web APIs, native desktop UI, language bridges, asynchronous I/O, source maps, debugger integration, or feature parity with the Python reference. Check the release scope before spending hours debugging an API that has not migrated yet.