Xo Language

Basics

Mon, 01 Jan 0001 00:00:00 +0000

basics/main.xo

const GREETING = "hello"

fn greet(name: Str) -> Str {
 "${GREETING}, ${name}"
}

fn sign(n: Int) -> Str {
 if n < 0 { "negative" } else if n == 0 { "zero" } else { "positive" }
}

fn main(os: Os) {
 let who = "Ada"
 var count = 0
 for i in 0..3 {
 count += i
 }
 os.stdio.println(greet(who))
 os.stdio.println("count = ${count}, sign = ${sign(count - 5)}")
}

Output:

Structs, enums, and newtypes

Mon, 01 Jan 0001 00:00:00 +0000

types/main.xo

struct User {
 id: Int
 name: Str
 email: Str?
} derive Display

enum Shape {
 Circle(radius: Float)
 Rect(w: Float, h: Float)
 Point
}

fn area(s: Shape) -> Float {
 match s {
 Circle(radius) => 3.14159 * radius * radius
 Rect(w, h) => w * h
 Point => 0.0
 }
}

type UserId = Int
type Email struct(Str)

fn domain(e: Email) -> Str {
 e.0.split("@").last() ?? ""
}

fn main(os: Os) {
 let ada = User{id: 1, name: "Ada", email: None}
 let renamed = ada with {name: "Ada L."}
 os.stdio.println("${ada}")
 os.stdio.println("${renamed.name}")
 let id: UserId = 7
 os.stdio.println("user ${id}, area ${area(Shape.Rect(w: 2.0, h: 3.0))}")
 os.stdio.println(domain(Email("ada@example.com")))
}

Output:

Lists, maps, and sets

Mon, 01 Jan 0001 00:00:00 +0000

collections/main.xo

fn show(xs: List[Int]) -> Str {
 xs.map(fn(x) { "${x}" }).join(" ")
}

fn main(os: Os) {
 var xs = [3, 1, 2]
 xs.push(5)
 let doubled = xs.map(fn(x) { x * 2 })
 let small = xs.filter(fn(x) { x < 3 })
 let total = xs.fold(0, fn(acc, x) { acc + x })
 os.stdio.println("sorted: ${show(xs.sort())}")
 os.stdio.println("doubled: ${show(doubled)}, small: ${show(small)}, total: ${total}")

 var ages: Map[Str, Int] = {"ada": 36}
 ages.put("grace", 85)
 ages["linus"] = 28
 let age = ages.get("ada") ?? 0
 os.stdio.println("ada is ${age}, ${ages.len()} people")
 for (name, a) in ages {
 os.stdio.println("${name}: ${a}")
 }

 var seen = ["x"].to_set()
 seen.add("x")
 seen.add("y")
 os.stdio.println("${seen.len()} unique")
}

Output:

No nil: optionals

Mon, 01 Jan 0001 00:00:00 +0000

There is no nil in Xo. A value that may be missing has type T? (an Option[T]): either Some(v) or None, and the compiler makes you look before you use it.

optionals/main.xo

struct User { name: Str, email: Str? }

fn contact(u: User) -> Str {
 if let Some(e) = u.email { "mail ${e}" } else { "no email for ${u.name}" }
}

fn port(s: Str) -> Int? {
 let n = Int.parse(s.trim())?
 if n > 0 && n < 65536 { n } else { None }
}

fn main(os: Os) {
 let a = User{name: "Ada", email: Some("ada@example.com")}
 let b = User{name: "Bob", email: None}
 os.stdio.println(contact(a))
 os.stdio.println(contact(b))
 os.stdio.println(b.email ?? "unknown")
 for s in [" 8080 ", "http", "70000"] {
 os.stdio.println("port(\"${s}\") = ${port(s) ?? -1}")
 }
}

Output:

Errors you have to handle

Mon, 01 Jan 0001 00:00:00 +0000

A function that can fail says so after !, and its caller gets a Result. Errors are ordinary values, usually an enum.

errors/main.xo

enum ConfigErr {
 NotANumber(s: Str)
 OutOfRange(n: Int)
}

fn (e: ConfigErr) display() -> Str {
 match e {
 NotANumber(s) => "not a number: ${s}"
 OutOfRange(n) => "out of range: ${n}"
 }
}

fn parse_port(s: Str) -> Int ! ConfigErr {
 let n = Int.parse(s).or_err(ConfigErr.NotANumber(s))?
 if n < 1 || n > 65535 {
 return Err(ConfigErr.OutOfRange(n))
 }
 n
}

enum StartErr {
 Config(from ConfigErr)
}

fn start(port: Str) -> Str ! StartErr {
 let p = parse_port(port)?
 "listening on ${p}"
}

fn main(os: Os) {
 for input in ["8080", "abc", "99999"] {
 match start(input) {
 Ok(msg) => os.stdio.println(msg)
 Err(Config(e)) => os.stdio.println("error: ${e.display()}")
 }
 }
 let fallback = parse_port("x").ignore_err("the default port is fine") ?? 8080
 os.stdio.println("fallback ${fallback}")
}

Output:

Why Xo? (FAQ)

Mon, 01 Jan 0001 00:00:00 +0000

How do you say “Xo”?

Ex-oh, like the letters X and O. When you search for it, use “Xo lang”: plain xo is also the name of a popular JavaScript linter.

What is Xo for?

Backends and web services: HTTP APIs, workers, command line tools. It is a small, statically typed, garbage collected language that compiles to static binaries for Linux, macOS, Windows, and WASI.

Why design a language for AI agents?

Agents now write a large share of backend code. They are fast, but they make the same mistakes people do (an ignored error, a nil, a forgotten case, a race), and they work best when every mistake comes back as precise, machine readable feedback. Xo is built around that loop:

Pattern matching

Mon, 01 Jan 0001 00:00:00 +0000

matching/main.xo

fn status_text(code: Int) -> Str {
 match code {
 200..=299 => "ok"
 429 | 503 => "retry later"
 404 => "not found"
 _ => "error"
 }
}

fn describe(xs: List[Int]) -> Str {
 match xs {
 [] => "empty"
 [x] => "one: ${x}"
 [first, .., last] => "from ${first} to ${last}"
 }
}

fn main(os: Os) {
 for c in [200, 503, 404, 500] {
 os.stdio.println("${c} ${status_text(c)}")
 }
 os.stdio.println(describe([]))
 os.stdio.println(describe([7]))
 os.stdio.println(describe([1, 2, 3]))
 let pair = (3, "three")
 let (n, word) = pair
 os.stdio.println("${n} ${word} ${pair is (3, _)}")
}

Output:

Values and mutation

Mon, 01 Jan 0001 00:00:00 +0000

Everything in Xo is a value: assigning or passing a struct copies it (cheaply, because collections share structure). There are no pointers, so two parts of a program can never change the same value without synchronization, and data races cannot happen.

mutation/main.xo

struct Account { owner: Str, balance: Int }

fn (var a: Account) deposit(amount: Int) requires amount > 0 {
 a.balance += amount
}

fn main(os: Os) {
 var acct = Account{owner: "ada", balance: 10}
 let snapshot = acct
 acct.deposit(5)
 os.stdio.println("now ${acct.balance}, snapshot ${snapshot.balance}")

 var accounts: Map[Str, Account] = {"ada": acct}
 accounts.update("ada", Account{owner: "ada", balance: 0}, fn(var a) { a.deposit(100) })
 let stored = accounts.get("ada").map(fn(a) { a.balance }) ?? 0
 os.stdio.println("stored ${stored}")

 let hits = Atomic[Int].new(0)
 let cache = Mutex[Map[Str, Int]].new({})
 cache.with(fn(var m) { m.put("k", hits.add(1)) })
 let size = cache.with_read(fn(m) { m.len() })
 os.stdio.println("hits ${hits.get()}, cache ${size}")
}

Output:

Effects and capabilities

Mon, 01 Jan 0001 00:00:00 +0000

In Xo, a function’s signature says what it can touch. The effects are net, fs, clock, rand, env, proc, and stdio. A pub function declares the ones it uses; one without a uses clause is pure.

effects/main.xo

pub fn banner(out: Stdio, name: Str) uses stdio {
 out.println("== ${name} ==")
}

pub fn slugify(s: Str) -> Str {
 s.trim().to_lower().replace(" ", "-")
}

fn main(os: Os) {
 banner(os.stdio, slugify(" Hello World "))
}

test "banner prints the name" {
 banner(os.stdio, "x")
 expect(os.stdio.output()) == "== x ==\n"
}

Output:

Structured concurrency

Mon, 01 Jan 0001 00:00:00 +0000

concurrency/main.xo

fn square(n: Int) -> Int { n * n }

fn main(os: Os) {
 let sum = scope s {
 let a = s.spawn(fn() { square(3) })
 let b = s.spawn(fn() { square(4) })
 a.await + b.await
 }
 os.stdio.println("sum ${sum}")

 let ch = Chan[Int].new(cap: 8)
 let total = scope s {
 s.spawn(fn() {
 for i in 1..=5 { ch.send(i) }
 ch.close()
 })
 var t = 0
 for x in ch { t += x }
 t
 }
 os.stdio.println("total ${total}")
}

Output:

Contracts and tests

Mon, 01 Jan 0001 00:00:00 +0000

contracts/main.xo

struct Account { id: Int, balance: Int } invariant balance >= 0

enum TxErr { Insufficient } derive Display

fn withdraw(a: Account, amount: Int) -> Account ! TxErr
 requires amount > 0
 requires a.balance >= amount else TxErr.Insufficient
 ensures result.balance == a.balance - amount
{
 a with {balance: a.balance - amount}
}

fn main(os: Os) {
 let a = Account{id: 1, balance: 50}
 match withdraw(a, 80) {
 Ok(b) => os.stdio.println("left ${b.balance}")
 Err(Insufficient) => os.stdio.println("insufficient funds")
 }
}

test "withdraw lowers the balance" {
 let b = withdraw(Account{id: 1, balance: 50}, 20)?
 expect(b.balance) == 30
}

test "reverse twice" for xs: List[Int] {
 expect(xs.reverse().reverse()) == xs
}

Output:

Xo Language Specification (Core)

Mon, 01 Jan 0001 00:00:00 +0000

Xo Language Specification (Core)

Status: draft 0.10 (2026-10-10; 0.9 released as toolchain v0.9.0, decision 0089) Edition: 2026 Companion: spec/std.md (prelude methods and standard library surface)

Xo is a small, statically typed, garbage collected language for backends and web services. It keeps what makes Go productive (few keywords, one obvious way, fast builds, static binaries, a strong standard library, a compatibility promise) and is designed so that an AI agent can write, check, build, and debug programs for any OS with fast, structured, unambiguous feedback.

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Xo is experimental, and the language may change before 1.0.

Build the toolchain

The source code is not public yet; it will be soon. Until then, the steps below show how the toolchain will be built, and the specification describes the whole language.

The toolchain is built from source with Go 1.26 or later. From a checkout of the repository:

go build -o .tools/bin/xo ./cmd/xo
export PATH="$PWD/.tools/bin:$PATH"

A first program

Make a directory and create the module:

A small web service

Mon, 01 Jan 0001 00:00:00 +0000

webservice/main.xo

use std/http

pub struct Todo {
 pub id: Int
 pub title: Str
 pub done: Bool
} derive Json

pub enum ApiErr {
 NotFound(id: Int)
}

fn (e: ApiErr) status() -> Int {
 match e {
 NotFound(_) => 404
 }
}

fn (e: ApiErr) display() -> Str {
 match e {
 NotFound(id) => "todo ${id} not found"
 }
}

fn find(todos: List[Todo], id: Int) -> Todo ! ApiErr {
 todos.find(fn(t) { t.id == id }).or_err(ApiErr.NotFound(id: id))
}

fn routes(todos: List[Todo]) -> http.Router {
 var r = http.router()
 r.handle("GET /todos", fn(_req) { http.json(200, todos) })
 r.handle("GET /todos/{id:Int}", fn(req) -> http.Response ! ApiErr {
 http.json(200, find(todos, req.param_int("id"))?)
 })
 r
}

fn main(os: Os) ! {
 let todos = [Todo{id: 1, title: "write the tour", done: false}]
 http.server(os.net.listen(":8080")?, routes(todos)).serve()?
}

test "missing todo is a 404" {
 let r = routes([])
 let resp = r.call(http.new_request("GET", "/todos/7"))
 expect(resp.status) == 404
 expect(resp.text() ?? "") == "{\"error\":\"todo 7 not found\"}"
}

Output:

Using Go packages

Mon, 01 Jan 0001 00:00:00 +0000

Until Xo has its own ecosystem, any Go package is one line away:

gointerop/main.xo

use go "strings"
use go "net/url"

fn main(os: Os) ! {
 os.stdio.println(strings.to_upper("hello from go"))
 let u = url.parse("https://xolang.dev/docs?tab=tour")?
 os.stdio.println("${u.hostname()} ${u.query().get("tab")}")
}

Output:

HELLO FROM GO
xolang.dev tour

xo check, build, run, and test generate the bindings themselves.
Names follow Xo’s style: ToUpper is to_upper.
Go’s (T, error) becomes T ! go.Error, so url.parse(...)? works like any Xo call, and a pointer that may be nil becomes T?.
Every call into Go performs the go effect. Go code can reach files and the network without a capability, so a pub function that calls Go must say uses go, and that escape stays visible in signatures.

Native builds can call C the same way with use c "header.h"; see section 4.5 of the specification.

Xo Standard Library

Mon, 01 Jan 0001 00:00:00 +0000

Xo Standard Library and Prelude

Status: draft 0.8 (2026-10-09; the same draft number as spec/core.md, decision 0089) Companion to spec/core.md.

Signatures are written in Xo syntax. [var] before a receiver means the method mutates and needs a var binding (core 3.4). Effects are listed with uses. Everything here is part of the 2026 edition compatibility promise once the edition is released.

0. Conventions

Capabilities and fakes are handles. Copying a Net, Fs, Clock, … or a test fake shares the same underlying resource. They can be captured in closures and stored in structs.
Every error type implements Display. So any std error converts to Error at a ? site.
Every error type returned by a blocking operation has a Canceled variant (core 7.2).
Functions that cannot fail have no !. Lookups that may miss return T?.
Braces are literal in plain strings (interpolation is ${x}), so route patterns are ordinary strings: "GET /users/{id}".
Fields of std structs are pub: they can be read and the structs can be constructed (useful for testing pure functions).

1. Prelude interfaces

Available everywhere without use.

Introducing Xo

Sat, 10 Oct 2026 12:00:00 -0400

Xo (pronounced ex-oh) is a small, statically typed language for backends and web services. It is built for a world where AI agents write much of the code, and it starts from one observation: agents make the same mistakes people do, only faster. They ignore an error, dereference a nil, forget a case, share a map between goroutines, or call the network from a function that looked pure. Tests catch some of these. Review catches some more. Many reach production.

Xo v0.9.0

Sat, 10 Oct 2026 00:00:00 +0000

Spec draft 0.9.

Module proxies (decision 0126): XO_PROXY lists proxy URLs, direct (git), and off, with Go’s fallback rules (comma after 404/410, pipe after any error; default direct), and XO_NOPROXY patterns go to git. The read only protocol serves @v/list, .mod, .zip, and .lock per module; xo mod proxy serve [--fetch] [<cache dir>] serves a module cache and can fill it from git, as a team cache. Proxied trees are checked against xo.lock exactly as git fetches are.
Checksum log (decision 0124): with XO_SUMDB=<name>+<id>+<key> [<url>], the first fetch of every module version must match the log’s record, be in its signed Merkle tree, and extend every tree the module cache saw before; otherwise XO1313 and nothing is cached. An unreachable log or malformed settings is XO1314; XO_NOSUMDB keeps private modules out. The default stays off (no public log yet).
Definition hashes (decision 0125, the last step of 0086): xo query hash <name> prints a content hash per top level definition that survives renaming locals and changes with what the definition, or one it calls in the module, computes. xo publish --check lists the definitions (private ones too) changed since the last tag, including those changed only through a helper, next to the API comparison.
std/http speaks HTTP/2 over TLS on every backend (decision 0121): with_tls servers and https clients agree on h2 by ALPN, plain http stays HTTP/1.1, and nothing in the API changes. Requests of a connection run at once, each as a task; a fault in a streamed body resets only its stream. The native backends implement it in C (frames, HPACK, flow control) with net/http’s limits (250 streams, the header list limit with 431, the rapid reset limit) and its error texts, and their client keeps HTTP/2 connections for later requests as Go’s does. Over one connection the native server does 87.8k requests per second in the HTTP benchmark, the Go backend 58.2k (bench/results/http2-2026-10-10.md).
Native test binaries (xo test --no-gc, decision 0120): property tests and testing.gen work, with the Go backend’s generated values for a seed, the same failing case, and the same shrunk input in the report. A Set or Map keyed by a sized integer (Set[Int8]) now builds natively. xo test --real gives native tests real capabilities for the effects they declare (fs, fs.read, fs.write, net, clock, env, stdio, proc), as on the Go backend.
Native backends: deferred code that faults no longer skips the rest of the cleanup. The deferred code registered before it and that of the blocks around it runs, the last fault is reported, as on the Go backend (core 3.5, decision 0085 amendment), and a task that caught such a fault with task.isolate sees cancellation again (it could deadlock before).
LLVM backend (decision 0119): generated code is compiled for the same CPU and features as the C runtime (clang’s defaults): LSE atomics for shared reference counts on darwin/arm64, outline atomics (LSE when the CPU has it) on Linux arm64. HTTP benchmark +3.5 percent.
Native Mutex (decision 0118): a writer’s release hands the lock to the readers waiting, so they no longer wake only to park again: a contended readers and writer load (bench/perf/conc rwmutex, new) went from 967 to 131 ms and from 6.3 to 0.25 s of CPU. Long lived scopes (the native HTTP server’s connections) no longer keep every finished task until they close, and the native allocator moves freed blocks between threads, so a server’s memory stays flat (28 MB instead of 295 MB after 300k TLS connections).
Native HTTPS (decision 0117): full TLS handshakes about 1.6 times as fast and at half the CPU (9.7k to 15k per second in the HTTP benchmark, Go backend 17k): X25519 key shares through HACL*, faster P-256 inverses, a spinning lock for Mbed TLS’s key store, SHA instructions. The native server now sends session tickets as Go’s does (TLS 1.3 resumption with ECDHE, TLS 1.2 tickets; keys rotate daily), so returning clients skip the certificate signature. bench/perf/http’s loadgen has -resume (RESUME=1 in run.sh).
xo lsp (decision 0114): a Language Server Protocol server with diagnostics and their fixes as quick fixes, hover (signature, doc, or type), definition (into std too), references, rename, document symbols, semantic tokens, and formatting. The VS Code extension starts it; ```xo fences in Markdown are highlighted.
VS Code syntax highlighting (decision 0113): editors/vscode/ registers .xo files with a TextMate grammar covering spec section 1 (keywords, contextual words, interpolation, raw and bytes strings, durations, sets, effects in uses). Install by symlinking it into ~/.vscode/extensions.
use c "<header>" [link "<lib>"]... [as name] [uses ...] on the native backends (decisions 0093 stage 2 and 0116): bindings generated from the header with clang (xo bind --c), scalars, Str, Bytes with a length, flat structs, and opaque handles at the boundary, the ffi effect unless the line narrows it, XO1104/XO1105 for headers and names that do not bind, XO1201 on the Go backend. Calls are not recorded yet (native builds do not record).
Decision 0111: passing one variable, or overlapping places (x and x.f, xs[i] and xs[j] unless both indexes are different literals, a var receiver and an argument naming it), to two var parameters of one call is XO0503 on every backend; the native backends no longer report XO1201 for it.
Decision 0112: a value that holds a handle (Mutex, Atomic, Chan, Task, Scope, Listener, Conn, task.Group, the std/http and std/sql handles, the test fakes) or a function value is not comparable: ==/!=, Map keys, Set elements, derive Eq/Hash, and T: Eq/Hash arguments are XO0404 with a note naming the field that holds it; derive Ord already was. The checker now looks into struct fields and enum payloads for Eq (it looked only at type arguments).
Native backends (decisions 0107 to 0109): Proc.run, os.tasks (a scope around main and around each test), method values (let f = x.method), map_concurrent_until, base64, Range.to_list, Rand.shuffle, target (a compile time constant), and in native test binaries MemFs (every method, fail_next, case sensitivity, files), FakeProc run and on_run, os.proc.exit inside testing.run_main, and run_main of a main that cannot fail. Fixed natively: a receive arm after an after arm lost its value; a ? in a closure printed the function’s frame name without .closure, and one in a Mutex.with closure none; FakeClock.advance returned before the tasks it woke ran; the success type of Err(e)? was XO1201. One binding passed to two var parameters is now XO1201 natively (the Go backend shares it, the native backends copied it).
TestCompileProperty (decision 0110): random checker valid programs over the optional syntax must build on the Go backend and with --no-gc, and run alike.
Fixes from Codex r3: a select arm that receives without binding the value no longer generates Go that fails to compile; the “propagate with ?” fix is offered only where ? can propagate; help notes for XO0205 in closures and for passing TestOs where Os is expected.
Native backends (--no-gc, LLVM and arm64): interface types as values (decision 0100): dynamic dispatch, adapters for methods that cannot fail, error conversion, interface to interface conversion, Display and Debug of the dynamic value, and ==; x.debug() on any value.
Native backends: newtypes (Email("x"), e.0 read and assigned, Email(p) patterns, Debug, ==, Map keys) and list patterns ([], [a, .., z]). Fixed: an or pattern whose alternatives bind the same name (Leaf(v) | Node(left: v, ..)) read the first alternative’s binding natively, a stale value when another alternative matched.
Native backends (decision 0101): Float32, Secret[T] redacted in every output path, Buf[T], < on derive Ord types, Int32.try and the other sized trys, Int.pow, clamp, min/max on Str, Set union, intersect, difference, Map.filter, List.insert, remove_at, indexed(), xs + ys, std defaults (crypto.token(r), Chan.new()), get_or_fault on any key type, builtin collections through interfaces, shorthand field patterns. == on a value holding a function or runtime handle outside an interface is now XO1201 natively (it failed in code generation). New test TestGenGoldensNative runs 66 internal/gen goldens on Go, LLVM, and arm64 and compares them.
Native backends: std/path (std/native/path.xo), task.semaphore, task.once (a fault in its function is not stored natively: the next caller runs it again), and task.map_concurrent (std/native/task.xo); Debug text of Result[T, Never] values. Fixed: natively, a task whose value is a Result failed its scope when that value was an Err; shorthand struct patterns Bag{items}.
Native backends (decision 0102): every Fs method and attenuation (sub, cwd, read_only, write_only, escapes Denied), Stdio.write, and standard input reads (read_line, read_all, lines) that a cancellation or a stop request ends with IoErr.Canceled. Fixed natively: task.with_timeout returns TimedOut when its closure finishes after the deadline without a cancellation point, as on the Go backend.
Native backends: error frames (decision 0104): each ? records the function, location, and parameters lazily, and main’s error report prints at ... lines identical to the Go backend’s.
Native Fs and standard input code is compiled into a program only when it calls them (XO_FS, XO_STDIN; hello world unchanged). Fixed: hybrid builds (--hybrid) declared a Bool result’s argument size rounded up (go vet -asmdecl).
xo test --no-gc: FakeStdio.set_input feeds the reads; fixed a hang after FakeProc.signal_after fired (the virtual clock stopped moving).
Native backends: all of std/time (decision 0094; std/native/time.xo and std/llrt/xo_time.c, a port of Go’s TZif reader and zone lookup): zones with the same per use embedded data (or --tzdata=system), civil time, gaps and overlaps, layouts, strict parsing with the same error texts and faults; also Duration.from_secs, scale, ceil_seconds, Time.parse_rfc3339, and Time.UNIX_EPOCH as a value. Programs that do not use std/time do not grow. TestTimeDiff compares about 70,000 lines with the Go backend. Fixed: the arm64 backend failed to assemble functions over 8192 instructions (tbz range).
HTTPS in std/http on every backend (std.md 4.6, decisions 0105 and 0106): http.tls_cert(cert_pem, key_pem), Server.with_tls(certs) (SNI picks among the certificates), Client.with_roots(pem), and TlsErr. The native backends (--no-gc) speak TLS 1.2 and 1.3 through Mbed TLS 4.1.1 (vendored in third_party/mbedtls, built once per compiler into the user cache, linked only into programs that use std/http), verify against the system’s roots on macOS and Linux, and report Go’s error texts; an https URL is no longer XO1201 there. std/http speaks HTTP/1.1 only, also over TLS: the Go backend’s client no longer negotiates HTTP/2. Failed TLS handshakes are not logged.
bench/perf/http/run.sh: SCHEME=https serves the Xo configs over TLS and NEWCONN=1 opens a connection (and a handshake) per request.

Xo v0.7.0

Fri, 09 Oct 2026 00:00:00 +0000

First tagged release. Spec draft 0.7.

Language: request scoped arenas by default, use go packages, two phase shutdown, Mutex.with_read, BytesBuilder, rune and integer conversions, native contracts and fault unwinding, habit diagnostics (XO0177), clock.sleep_or_cancel, cancellable stdin, tuple JSON, Duration.parse (decisions 0041 to 0088).
Backends: Go (default), LLVM, native arm64, --no-gc, --hybrid.
Toolchain: xo version.
Planned before 1.0: modules and workspaces (0086), std/time, native TLS, and decisions on the Appendix B questions.

Xo v0.8.0

Fri, 09 Oct 2026 00:00:00 +0000

Spec draft 0.8.

Modules (decision 0086 steps 1 and 2): require <path> <version> of Xo modules, minimal version selection, git fetch into a read only module cache, xo.lock hashes verified on every build, xo get, xo mod tidy, xo vendor, xo mod clean, --offline, and xo.work workspaces (--workspace=off). Diagnostics XO1301 to XO1308.
Codex r2 first run failures: XO0175 for several match arms on one line has a split fix and no longer cascades into a false XO0301; .display() works on every Display type (derived, std errors, builtins); a closure that never completes infers Never instead of XO0402.
Effect ceilings and checked semver (decision 0086 steps 3 and 4): require <path> <version> uses none in xo.mod and use <dir> uses ... in xo.work (XO1309 at a call above the ceiling), API and effect diffs from xo get (and xo get -u), xo publish [--check] against the previous tag (XO1310, XO1311; prints the tag command, never pushes), xo init, /vN major version module paths, and xo serve noticing a new or changed xo.work above the directories.
std/time (decision 0094, Go backend): zones with per use embedded data (--tzdata=system), civil dates and times with explicit daylight saving gaps and overlaps, layouts with named fields checked at compile time (XO0420; XO0177 for {yyyy}, %Y, 2006-01-02 habits).
Import direction rules (decision 0095): deny <pkg> -> <pkg>, ... lines in xo.mod with /... patterns, checked at every use line (new code XO1312; a rule naming no package is XO1301), kept by xo mod tidy; xo query imports and xo query deps list the use lines (also in the MCP query tool).
std/time error text (std.md 13): ZoneErr and CivilErr display as sentences (unknown time zone "Mars/Olympus", 2026-03-08T02:30:00 America/New_York does not exist (skipped by a daylight saving change)) instead of the derived Skipped(at: ...) form, matching ParseErr and LayoutErr.
Newtypes (decision 0097, spec audit gap 4): e.0 reads the underlying value and Email(s) destructures it in let and match.
xo check --fix (decision 0096): applies the unambiguous machine fixes (as xo fix), reformats, then reports what remains plus an applied list; the MCP check tool takes fix, and the bench harness agent loop uses it while still scoring first runs as written and after fix.
Go backend output (decision 0098): hello world 7.9 to 3.6 MB, Go build cache growth per program 34 to 2.9 MB, compile memory 286 to 123 MB. Binaries carry no DWARF or symbol table (XO_GO_DWARF=1 keeps them for a debugger); programs that do not import std/http do not link net/http.
Spec audit second pass: x.debug() works on every value (std.md 1; was XO0601 on concrete types); new tests for single field positional variants, Secret redaction in Debug and log fields, target at run time, Stdio.write, Fs.cwd, Fs.case_sensitive, a real Proc.run, XO-F005, xo test --real, and byte identical rebuilds (spec 12.1 now says “in the same directory”).
Modules in repository subdirectories (decision 0086): a module path github.com/acme/tools/cli is the directory cli/ of the repository github.com/acme/tools, versioned by tags cli/vX.Y.Z (as Go); fetch, MVS, xo.lock, xo vendor, xo get, and xo publish [--check] (prefixed tag command) handle it; nested modules are left out of a module’s tree and hash.
Go calls in record and replay (decision 0093 stage 1): --record records use go calls whose arguments and results are values (an argument hash and the results) and xo replay answers them without calling Go; calls with a Go handle or a callback run again and the replay reports re executed foreign call `<name>` ; pure std packages and xo.mod replay rerun go <path> [names] lines are not recorded. Binding format v5; traces gain "foreign": 1, and older traces still replay (every Go call runs again).
Release builds (decision 0099): xo build --release compiles out requires(debug) and ensures(debug) on every backend and reports XO1308 for workspace overrides; --ci does not imply it.
Lazy error frames (decision 0092, Go backend): frames keep copies of the parameter values and format them, bounded to 64 bytes, only when a trace is printed. 1,000,000 errors through 5 frames: 0.93 s to 0.10 s with short parameters, 2.78 s to 0.10 s with 90 byte ones; error output unchanged. xo build --release --error-args=false drops the values.

XO0101: name breaks the enforced naming rules

Mon, 01 Jan 0001 00:00:00 +0000

Xo enforces naming in the compiler instead of leaving it to linters, so every program reads the same way and a name’s kind is visible at a glance. Types, enum variants, interfaces, and type parameters are UpperCamel; functions, methods, variables, fields, parameters, modules, and effect variables are snake_case; constants are UPPER_SNAKE. Exported names are marked with pub, never by capitalization. The diagnostic carries a fix that renames the declaration. See core 1.5.

XO0110: unused local binding or import

Mon, 01 Jan 0001 00:00:00 +0000

A local let or var binding, a local constant, a pattern binding, or an import that is never read is an error, because dead names usually mean a forgotten step. Function and closure parameters, names starting with _, and _ itself are not covered. A var that is only assigned and never read also counts as unused. xo fix removes unused bindings. See core 3.1.

Example

use std/json

fn f() -> Int {
 let x = 1
 2
}

Fix

fn f() -> Int {
 let x = 1
 x + 1
}

Run xo explain XO0110 for this text in a terminal, or see section 10.6 of the specification.

XO0150: character that cannot start any token

Mon, 01 Jan 0001 00:00:00 +0000

The lexer found a character that begins no Xo token, such as @ or a stray Unicode symbol outside a string or comment. Xo source is UTF-8 and identifiers are [A-Za-z_][A-Za-z0-9_]*. Remove the character or move it into a string literal. See core 1.1 and 1.5.

Example

fn f(x: Int) -> Int {
 x @
}

Fix

fn f(x: Int) -> Int {
 x
}

Run xo explain XO0150 for this text in a terminal, or see section 10.6 of the specification.

XO0151: string, raw string, bytes, or triple quoted string not closed

Mon, 01 Jan 0001 00:00:00 +0000

A string literal "...", raw string r"..." or r#"..."#, bytes literal b"...", or triple quoted string """...""" reached the end of the line (or file, for triple quoted strings) without its closing delimiter. Plain strings cannot span lines; use a triple quoted string for multi line text. A raw string opened with r#" must close with "#. See core 1.6.

Example

fn f() -> Str {
 let s = "abc
 s
}

Fix

fn f() -> Str {
 let s = "abc"
 s
}

Run xo explain XO0151 for this text in a terminal, or see section 10.6 of the specification.

XO0152: rune literal that is empty, unterminated, or holds more than one character

Mon, 01 Jan 0001 00:00:00 +0000

A rune literal is exactly one character (or one escape) between single quotes: 'a', '\n', '\u{1F600}'. '', 'ab', and an unclosed 'a are rejected. Text of several characters is a Str and uses double quotes. See core 1.6.

Example

fn f() -> Str {
 let s = 'ab'
 "${s}"
}

Fix

fn f() -> Str {
 let s = "ab"
 s
}

Run xo explain XO0152 for this text in a terminal, or see section 10.6 of the specification.

XO0153: unknown or malformed escape sequence

Mon, 01 Jan 0001 00:00:00 +0000

Escapes in Str and Bytes are \n \t \r \0 \\ \" \' \$ \xHH \u{...}. Anything else after a backslash is an error, as are \x without two hex digits, \u without braces, an invalid code point, and in Str a \xHH above \x7f (use \u{...} for non ASCII text). To write a backslash, double it, or use a raw string r"...", which has no escapes. See core 1.6.

XO0154: bad digit, misplaced `_`, missing digits, or out of range integer

Mon, 01 Jan 0001 00:00:00 +0000

Integer literals are decimal, 0x hex, 0b binary, or 0o octal, with _ allowed only between digits (1_000_000). The lexer rejects a digit that does not belong to the base (0b102), a prefix with no digits (0x), a doubled, leading, or trailing _, an integer that does not fit in 64 bits, and a duration literal whose nanosecond count overflows. See core 1.6.

Example

const LIMIT = 1__000

Fix

const LIMIT = 1_000

Run xo explain XO0154 for this text in a terminal, or see section 10.6 of the specification.

XO0155: unknown duration unit, fractional or non decimal duration

Mon, 01 Jan 0001 00:00:00 +0000

A duration literal is a decimal integer followed by one of ns, us, ms, s, m, or h: 5s, 250ms. Any other suffix on a number (5sec, or 0xg, where g is read as a suffix) is reported here, and so are fractional or non decimal durations such as 1.5s or 0x10s. Write a fractional duration in a smaller unit: 1500ms. See core 1.6.

Example

const TIMEOUT = 1.5s

Fix

const TIMEOUT = 1500ms

Run xo explain XO0155 for this text in a terminal, or see section 10.6 of the specification.

XO0156: `${` without a matching `}` in the same string

Mon, 01 Jan 0001 00:00:00 +0000

Inside a string, ${ starts an interpolated expression that must be closed by } before the string ends. If a literal ${ is meant, escape the dollar sign: \${. A $ not followed by { is always literal. See core 1.6.

Example

fn f(b: Int) -> Str {
 "a ${b"
}

Fix

fn f(b: Int) -> Str {
 "a ${b}"
}

Run xo explain XO0156 for this text in a terminal, or see section 10.6 of the specification.

XO0157: `${}` with no expression

Mon, 01 Jan 0001 00:00:00 +0000

An interpolation must contain an expression whose type implements Display. ${} (or ${ }) has nothing to interpolate. Put an expression inside, or escape the dollar sign (\${}) to write the characters literally. See core 1.6.

Example

fn f() -> Str {
 "a ${}"
}

Fix

fn f() -> Str {
 "a \${}"
}

Run xo explain XO0157 for this text in a terminal, or see section 10.6 of the specification.

XO0158: `use` not followed by a valid import path

Mon, 01 Jan 0001 00:00:00 +0000

use takes a slash separated module path (use std/http, use github.com/acme/billing/invoice) or, for Go packages, use go "path" with a non empty, relative, plain string. Empty segments (std//http), a missing path, an empty or absolute Go path, and interpolation in a Go path are rejected. See core 4.1 and 4.4.

Example

use std//http

fn ok() -> http.Response { http.text(200, "ok") }

Fix

use std/http

fn ok() -> http.Response { http.text(200, "ok") }

Run xo explain XO0158 for this text in a terminal, or see section 10.6 of the specification.

XO0160: a token that does not fit the grammar here

Mon, 01 Jan 0001 00:00:00 +0000

The general syntax error: the parser expected one thing (an expression, ,, ), a type, in in a for, …) and found another. The message names what was expected and what was found. It is also used for a keyword written where a name is needed, bitwise compound assignments (only += -= *= /= %= exist), an interface method with a body, and a statement such as return used as a value. The parser recovers at the next statement, so one mistake gives one diagnostic. See core 15 for the grammar.

XO0161: list element followed by a newline instead of a comma

Mon, 01 Jan 0001 00:00:00 +0000

Newlines end statements (core 1.3), so a comma separated list (arguments, list, map, or struct literal elements, parameters) that spans lines needs a comma after every element, including the last one. Trailing commas are allowed in every list. The diagnostic carries a fix that inserts the comma. See core 1.3.

Example

fn f() -> List[Int] {
 let xs = [
 1,
 2
 ]
 xs
}

Fix

fn f() -> List[Int] {
 let xs = [
 1,
 2,
 ]
 xs
}

Run xo explain XO0161 for this text in a terminal, or see section 10.6 of the specification.

XO0162: `else` must be on the line of the closing brace

Mon, 01 Jan 0001 00:00:00 +0000

Because a newline after } ends the if statement (core 1.3), an else on the next line would start a new statement. Write } else { and } else if on the same line as the closing brace. See core 1.3.

Example

fn f(a: Bool) -> Int {
 if a {
 1
 }
 else {
 2
 }
}

Fix

fn f(a: Bool) -> Int {
 if a {
 1
 } else {
 2
 }
}

Run xo explain XO0162 for this text in a terminal, or see section 10.6 of the specification.

XO0163: unparenthesized struct literal in a condition

Mon, 01 Jan 0001 00:00:00 +0000

In the condition of if, while, for, match, requires, or ensures, a { opens the body, so a struct literal or struct pattern (p is Point{x: 0, ..}) there is ambiguous. Parenthesize the condition, as in Go. The diagnostic carries that fix. See core 1.4.

Example

struct Point { x: Int }

fn f(p: Point) -> Bool {
 if p == Point{x: 0} {
 true
 } else {
 false
 }
}

Fix

struct Point { x: Int }

fn f(p: Point) -> Bool {
 if (p == Point{x: 0}) {
 true
 } else {
 false
 }
}

Run xo explain XO0163 for this text in a terminal, or see section 10.6 of the specification.

XO0164: `(`, `[`, or `{` not closed before end of file

Mon, 01 Jan 0001 00:00:00 +0000

The file ended while a delimiter was still open. The diagnostic points at the opening delimiter and notes where the file ended. The prototype reports this for an unclosed {; an unclosed ( or [ currently surfaces as XO0160 at the token that cannot continue the list. See core 15.

Example

fn f() -> Int {
 1

Fix

fn f() -> Int {
 1
}

Run xo explain XO0164 for this text in a terminal, or see section 10.6 of the specification.

XO0165: syntax that is not a pattern

Mon, 01 Jan 0001 00:00:00 +0000

Where a pattern is expected (a match arm, let, if let, for, or after is), the parser found something that is not one: an operator, a missing pattern after let, or a non literal in a range pattern. A pattern after is tests without binding, so it may not bind names: write _, or bind with if let or match. See core 3.5 for the pattern table.

Example

fn f(r: Result[Int, Str]) -> Bool {
 r is Ok(v)
}

Fix

fn f(r: Result[Int, Str]) -> Bool {
 r is Ok(_)
}

Run xo explain XO0165 for this text in a terminal, or see section 10.6 of the specification.

XO0166: `while cond` used as an expression; only `while { }` is one

Mon, 01 Jan 0001 00:00:00 +0000

A while loop with a condition may end without producing a value, so it is a statement. Only the infinite loop while { ... } is an expression, whose value comes from break. Move the loop into its own statement and compute the value separately. See core 3.5.

Example

fn f(a: Bool) {
 let x = while a { }
}

Fix

fn f(a: Bool) {
 while a { }
}

Run xo explain XO0166 for this text in a terminal, or see section 10.6 of the specification.

XO0167: top level declaration inside a block

Mon, 01 Jan 0001 00:00:00 +0000

fn, struct, enum, interface, type, use, test, and anything marked pub may appear only at the top level of a file. Inside a function, use a closure (let name = fn(...) { ... }) instead of a nested function. const is the exception: local constants are allowed in blocks. See core 3.1, 3.3, and 15.

Example

fn f() -> Int {
 fn g() -> Int { 1 }
 g()
}

Fix

fn f() -> Int {
 let g = fn() -> Int { 1 }
 g()
}

Run xo explain XO0167 for this text in a terminal, or see section 10.6 of the specification.

XO0168: statement (let, expression, ...) at top level

Mon, 01 Jan 0001 00:00:00 +0000

A file holds only use declarations and declarations (fn, struct, enum, interface, type, const, test). Statements such as let, assignments, and expressions are allowed only inside a function or test body. A module level value is a const. See core 15 (File).

Example

let max_users = 10

fn f() -> Int { max_users }

Fix

const MAX_USERS = 10

fn f() -> Int { MAX_USERS }

Run xo explain XO0168 for this text in a terminal, or see section 10.6 of the specification.

XO0169: match or select arms separated by `,` instead of newlines

Mon, 01 Jan 0001 00:00:00 +0000

match and select arms are separated by newlines, not commas, so arms read like statements. Remove the comma. See core 3.5.

Example

fn f(b: Bool) -> Int {
 match b {
 true => 1,
 false => 2
 }
}

Fix

fn f(b: Bool) -> Int {
 match b {
 true => 1
 false => 2
 }
}

Run xo explain XO0169 for this text in a terminal, or see section 10.6 of the specification.

XO0170: several effects in a function type must be parenthesized

Mon, 01 Jan 0001 00:00:00 +0000

In a function type, uses a, b would be ambiguous with the comma that separates parameters or fields, so several effects are written uses (a, b). In a declaration clause (fn f() uses net, clock) the parentheses are optional. The diagnostic carries a fix that adds them. See core 6.2 and 15.

Example

fn f(g: fn() uses net, clock, n: Int) uses (net, clock) {
 g()
}

Fix

fn f(g: fn() uses (net, clock), n: Int) uses (net, clock) {
 g()
}

Run xo explain XO0170 for this text in a terminal, or see section 10.6 of the specification.

XO0171: `..` used more than once or not last in pattern fields

Mon, 01 Jan 0001 00:00:00 +0000

In variant and struct patterns, .. ignores the remaining fields and must come last: Db(msg: m, ..). A list pattern may contain .. once, anywhere: [first, .., last]. .. is not allowed outside list, variant, and struct patterns. See core 3.5.

Example

enum E { Db(msg: Str, code: Int) }

fn f(e: E) -> Int {
 match e {
 Db(.., code: c) => c
 }
}

Fix

enum E { Db(msg: Str, code: Int) }

fn f(e: E) -> Int {
 match e {
 Db(code: c, ..) => c
 }
}

Run xo explain XO0171 for this text in a terminal, or see section 10.6 of the specification.

XO0172: function declaration without a body

Mon, 01 Jan 0001 00:00:00 +0000

Every fn declaration outside an interface needs a { ... } body. Only interface method signatures have no body. If the body is not written yet, use a typed hole ??? (core 3.7) so the rest of the program still checks. See core 3.2 and 15.

Example

fn f() -> Int
fn g() {}

Fix

fn f() -> Int { ??? }
fn g() {}

Run xo explain XO0172 for this text in a terminal, or see section 10.6 of the specification.

XO0173: `use` after the first declaration

Mon, 01 Jan 0001 00:00:00 +0000

All use declarations of a file come first, before any fn, struct, or other declaration, so a file’s imports are visible at the top. Move the use up. See core 4.1 and 15 (File).

Example

fn f() -> Int { 1 }
use std/http

fn ok() -> http.Response { http.text(200, "ok") }

Fix

use std/http

fn f() -> Int { 1 }

fn ok() -> http.Response { http.text(200, "ok") }

Run xo explain XO0173 for this text in a terminal, or see section 10.6 of the specification.

XO0174: bare `self` parameter outside an interface method signature

Mon, 01 Jan 0001 00:00:00 +0000

A bare self parameter is only allowed first in an interface method signature (fn get(self, id: Int) -> T?). A method on a concrete type names its receiver before the method name: fn (p: Point) norm() -> Int. See core 2.4 and 3.4.

Example

struct P { x: Int }

fn norm(self, scale: Int) -> Int { scale }

Fix

struct P { x: Int }

fn (p: P) norm(scale: Int) -> Int { p.x * scale }

Run xo explain XO0174 for this text in a terminal, or see section 10.6 of the specification.

XO0175: two statements or arms on one line

Mon, 01 Jan 0001 00:00:00 +0000

Newlines terminate statements and separate declarations and match arms, and Xo has no semicolons in source (core 1.3). Two statements, declarations, or arms on one line are rejected. Put each on its own line. Several match or select arms on one line (match r { Ok(v) => v Err(_) => 0 }) get a machine fix that puts each arm on its own line (xo fix), and the parser keeps every arm, so no false missing arm error (XO0301) follows.

XO0176: `pub` before something that cannot be exported

Mon, 01 Jan 0001 00:00:00 +0000

pub exports a declaration from its module (core 1.5). Imports (use) and test blocks cannot be exported, so pub use and pub test are rejected. Remove the pub.

Example

pub test "adds" {
 expect(1 + 1) == 2
}

Fix

test "adds" {
 expect(1 + 1) == 2
}

Run xo explain XO0176 for this text in a terminal, or see section 10.6 of the specification.

XO0177: syntax from another language (Go, Rust, TypeScript, Python, Swift, Kotlin); names the habit and the Xo form (decision 0087)

Mon, 01 Jan 0001 00:00:00 +0000

The code uses a form that is correct in Go, Rust, TypeScript, Python, Swift, or Kotlin but not in Xo. The message names the habit and the Xo form, and when the rewrite is unambiguous a machine fix applies it (xo fix). The parser then continues as if the Xo form had been written, so one habit gives one diagnostic. Common ones: func, fun, def, function are fn; x := v and Kotlin val are let (or var); Rust let mut is var; T: Hash + Eq is one constraint, T: Hash (Eq and Debug are automatic); Vec<T> and []T are List[T], map[K]V is Map[K, V]; var x or &x at a call site is just x (var belongs on the parameter); *p, &T, and *T have no Xo form (no pointers); c ? a : b and Python’s a if c else b are if c { a } else { b }; Kotlin ?: is ??; x!! and x! are x.or_fault("why"); switch/case and Kotlin when are match with pattern => body arms; elif is else if; and, or, not are &&, ||, !; x in xs is xs.contains(x); for i := 0; i < n; i++ is for i in 0..n; Go for k, v := range m is for (k, v) in m (the checker names the form for the type); for cond is while cond; loop and for {} are while {}; 0..<n is 0..n, Swift 0...n is 0..=n, Kotlin until is ..; x++ is x += 1; === is ==; ** is .pow(n); xs[a:b] is xs[a..b]; throw e and raise e are return Err(e); Swift try f() is f()? and throws is ! Error; try/catch has no Xo form (handle the Result); |x| e, (x) => e, and lambda x: e are fn(x) { e }; x as T is T(x); A::B is A.B; impl T { fn m(&self) } is fn (self: T) m() at top level; trait is interface; ): T and Go’s bare result type are -> T; Go (T, error) results are -> T ! Error, and return v, nil is return v; x, err := f() with if err != nil { return err } is let x = f()?; backtick templates and Python f-strings are "...${x}..."; /* */ is //. See decision 0087 for the policy.

XO0178: a line starts with a binary operator; end the previous line with it

Mon, 01 Jan 0001 00:00:00 +0000

A newline ends a statement when the line’s last token is an identifier, literal, ), ], }, ?, or return, break, continue (core 1.3, Go’s rule). So an expression continued on the next line must leave its operator at the end of the first line: a line that starts with ||, &&, +, ==, ??, or another binary operator would begin a new statement. Rust, Swift, Kotlin, and some Go style guides put the operator first; Xo cannot, because -x, !x, and ..n start expressions and a leading || reads as a closure. The machine fix moves the operator to the end of the previous line, and the parser reads the expression as continued, so no other error follows. A line starting with . continues a method chain and is allowed. See decision 0136.

XO0201: Result value is never used

Mon, 01 Jan 0001 00:00:00 +0000

Handling errors is mandatory. A Result value that is not propagated with ?, matched, passed, returned, or stored is an error, and so is a Result bound to a name that is never used, whatever the name (including _x). This covers expression statements, defer, loop bodies, if without else, and the tail of a unit function or closure. The diagnostic offers ? as a fix. To discard on purpose, write .ignore_err("reason"). See core 2.6.

XO0202: error type does not convert to the enclosing error type

Mon, 01 Jan 0001 00:00:00 +0000

expr? on a Result[T, E2] returns the error from the enclosing function, so E2 must convert to its error type E: E2 is E, or E is Error and E2 implements Display, or E has a from E2 variant. Add a from variant, derive Display for an Error target, or convert inline with map_err. The same rule applies inside a closure whose error type is fixed. See core 2.6.

Example

enum LoadErr { Timeout }
enum ApiErr { Bad }

fn g() -> Int ! LoadErr { 1 }

fn f() -> Int ! ApiErr { g()? }

Fix

enum LoadErr { Timeout }
enum ApiErr { Bad, Load(from LoadErr) }

fn g() -> Int ! LoadErr { 1 }

fn f() -> Int ! ApiErr { g()? }

Run xo explain XO0202 for this text in a terminal, or see section 10.6 of the specification.

XO0203: success of a Result typed T must be written Ok(x)

Mon, 01 Jan 0001 00:00:00 +0000

In a function declared -> T ! E, a returned T means success and a returned Result[T, E] is passed through as is. When T is itself a Result, a returned Result would be ambiguous, so success must be written Ok(x) explicitly. The same applies to closures whose results are collected, as in xs.map(fn(x) { Ok(g()) }). See core 2.6.

Example

enum E { A }

fn f(r: Result[Int, Str]) -> Result[Int, Str] ! E { r }

Fix

enum E { A }

fn f(r: Result[Int, Str]) -> Result[Int, Str] ! E { Ok(r) }

Run xo explain XO0203 for this text in a terminal, or see section 10.6 of the specification.

XO0204: `?` on an Option in a function returning a Result

Mon, 01 Jan 0001 00:00:00 +0000

opt? returns None from a function that returns an optional. In a function that returns a Result there is no error value to return for None, so say which error a missing value is: opt.or_err(E.Missing)?. The diagnostic offers that fix. See core 2.5.

Example

enum E { Missing }

fn f(s: Str?) -> Str ! E { s? }

Fix

enum E { Missing }

fn f(s: Str?) -> Str ! E { s.or_err(E.Missing)? }

Run xo explain XO0204 for this text in a terminal, or see section 10.6 of the specification.

XO0205: `?` where the enclosing function cannot return the failure

Mon, 01 Jan 0001 00:00:00 +0000

? on a Result needs a function or closure that can fail, and ? on an optional needs one that returns an optional. A function without ! cannot propagate an error, and a requires ... else clause in such a function has nowhere to return its error either. Declare the error type (the diagnostic offers ! E as a fix), or handle the failure with match, ??, or ignore_err. See core 2.5 and 2.6.

XO0206: `let _ =` discards a Result; use `.ignore_err("reason")`

Mon, 01 Jan 0001 00:00:00 +0000

let _ = expr on a Result silently drops its error. Xo requires a reason instead: expr.ignore_err("why this failure does not matter") yields T? and records the reason, so every discarded error is searchable and reviewable (xo vet lists them, XO0208). The diagnostic carries a fix that inserts .ignore_err("TODO: reason"). Use r.ok() when failure simply means no value. See core 2.6.

Example

fn f(fs: Fs) uses fs.write {
 let _ = fs.remove("tmp")
}

Fix

fn f(fs: Fs) uses fs.write {
 let _ = fs.remove("tmp").ignore_err("best effort temp file cleanup")
}

Run xo explain XO0206 for this text in a terminal, or see section 10.6 of the specification.

XO0207: method chain on the right of `??` starts at a literal

Mon, 01 Jan 0001 00:00:00 +0000

Reported by xo vet, not xo check. A method call binds tighter than ?? (core 15 precedence), so in x ?? [].f() the call .f() applies only to the default [], not to the unwrapped x. That is rarely what was meant when the chain starts at a literal. If the chain should apply to both, parenthesize the coalesce: (x ?? []).f(). If it really is only for the default, bind the default to a name to make that clear.

XO0208: `.ignore_err("reason")` discards an error; listed for review

Mon, 01 Jan 0001 00:00:00 +0000

Reported by xo vet as a note, never an error. Every .ignore_err("reason") throws away an error, and its reason is the only record of why that is safe (core 2.6). xo vet lists each one with its reason so a reviewer can confirm the reason still holds, catch placeholder reasons such as the TODO: reason inserted by the XO0206 fix, and decide whether the error should be handled after all.

XO0301: match does not cover every case

Mon, 01 Jan 0001 00:00:00 +0000

A match must cover every value of its subject. The message lists example patterns that are missing (such as C, Some(Err(_)), [_], or _ for integers and strings). Guarded arms (if ...) do not count toward coverage. A match on target.os must name every OS, so a missing platform fails on every host. Add the missing arms. For an enum declared in the same module, list the variants rather than adding _ (XO0305). See core 2.3 and 3.5.

XO0302: pattern does not fit the type of the matched value

Mon, 01 Jan 0001 00:00:00 +0000

The pattern can never match because it describes a different type: a variant of another enum, Ok on an optional, a literal of the wrong type, a tuple of the wrong size, a list pattern on a non list. It also covers malformed variant and struct patterns: parentheses on a variant without fields (or none on one with fields), too many or repeated fields, and fields left unmentioned without ... See core 3.5.

XO0303: refutable pattern where an irrefutable one is required

Mon, 01 Jan 0001 00:00:00 +0000

let and for bind every value they get, so their patterns must match every value of the type, such as (a, b) for a tuple or P{x, y} for a struct. A pattern that can fail, such as Some(v), needs a construct that says what happens otherwise: if let, match, ??, or ?. The message names a value that is not covered. See core 3.5.

Example

fn f(o: Int?) -> Int {
 let Some(v) = o
 v
}

Fix

fn f(o: Int?) -> Int {
 if let Some(v) = o { v } else { 0 }
}

Run xo explain XO0303 for this text in a terminal, or see section 10.6 of the specification.

XO0304: alternatives of an or pattern bind different names or types

Mon, 01 Jan 0001 00:00:00 +0000

The arm body of p1 | p2 runs for either alternative, so every alternative must bind the same names with the same types; otherwise a name would be unbound in one case. Bind the name in every alternative, or bind it in none and use separate arms. See core 3.5.

Example

fn f(r: Result[Int, Int]) -> Int {
 match r {
 Ok(v) | Err(_) => v
 }
}

Fix

fn f(r: Result[Int, Int]) -> Int {
 match r {
 Ok(v) | Err(v) => v
 }
}

Run xo explain XO0304 for this text in a terminal, or see section 10.6 of the specification.

XO0305: `_` arm hides variants of an enum declared in this module

Mon, 01 Jan 0001 00:00:00 +0000

Warning. An unguarded _ or catch all binding arm on an enum declared in the same module hides the variants it covers, so adding a variant later compiles silently instead of failing at every match. List the variants (an or pattern such as B | C keeps it short). Enums from other modules, the prelude (Option, Result), and non enum values may use _, since their owners can add variants. A _ arm that hides at least 8 variants and more than half of the enum is a deliberate default and is not reported (decision 0080). See core 3.5.

XO0401: value of the wrong type; only three implicit conversions exist

Mon, 01 Jan 0001 00:00:00 +0000

The value’s type is not the expected one. Xo converts implicitly in exactly three cases, each only where the target type is known: T to T?, a value to an interface it implements, and an error at ? to the enclosing error type. Everything else is explicit, including all numeric conversions (Float(i)) and newtypes (Email(s)). Branches of if and match must already agree; annotate the binding to give them an expected type. See core 2.10.

XO0402: type arguments cannot be inferred

Mon, 01 Jan 0001 00:00:00 +0000

A generic function’s type parameter was determined by nothing: not the arguments, the expected type, or later use. Write the type argument explicitly (json.decode[Int](b)), or give the result an expected type. See core 2.7.

Example

use std/json

fn f(b: Bytes) -> Int {
 let _ = json.decode(b).ok()
 1
}

Fix

use std/json

fn f(b: Bytes) -> Int {
 let _ = json.decode[Int](b).ok()
 1
}

Run xo explain XO0402 for this text in a terminal, or see section 10.6 of the specification.

XO0403: wrong arguments or fields: count, names, missing, or duplicates

Mon, 01 Jan 0001 00:00:00 +0000

A call, struct literal, variant construction, or type application does not match its declaration: too many or too few arguments, an unknown or repeated parameter name, a positional argument after a named one, a missing struct field without a default, or the wrong number of type arguments. Variants with several fields are constructed with names (A(x: 1, y: 2)), and ignore_err needs its reason. See core 2.2, 2.3, and 3.2.

XO0404: type does not implement a required interface or constraint

Mon, 01 Jan 0001 00:00:00 +0000

The value is used in a way that needs an interface its type does not implement: interpolation needs Display, == needs Eq, < needs Ord, json.encode needs Json, a generic call needs its constraint (T: Ord), and derive X needs every field to implement X. A value that holds a handle (Mutex, Atomic, Chan, Task, Conn, …) or a function value is never Eq or Hash: it cannot be compared, be a Map key or Set element, or derive Eq, Hash, or Ord (decision 0112); compare an identifying field instead. Add derive to the type, implement the interface’s methods, or convert the value first. See core 2.4 and 2.9.

XO0405: type cannot be inferred here; annotate it

Mon, 01 Jan 0001 00:00:00 +0000

The checker needs a type at this point and nothing determines it yet: a closure parameter with no expected function type, a value whose method or field is used before its type is known, a match subject, or an iterated value. Add a type annotation to the parameter or binding. See core 3.3.

Example

fn f() -> Int {
 let g = fn(p) { p }
 g(1)
}

Fix

fn f() -> Int {
 let g = fn(p: Int) -> Int { p }
 g(1)
}

Run xo explain XO0405 for this text in a terminal, or see section 10.6 of the specification.

XO0406: operator, index, slice, or iteration not defined for the type

Mon, 01 Jan 0001 00:00:00 +0000

The operation does not exist for this type: arithmetic between Duration and a plain integer literal, Time + Time, indexing a Str by position, slicing something other than List, Bytes, or Str, for over a value that is not a List, Set, Map, Chan, Bytes, or range, ?? on a non optional, or expect(x) without a comparison. Durations need units (5s), and a Str is read with runes() or by slicing. See core 2.1, 3.5, and 3.6.

XO0407: name used as the wrong kind of thing

Mon, 01 Jan 0001 00:00:00 +0000

A name resolved, but to the wrong kind of entity: a type used as a value, a module or constant called like a function, a value given type arguments, a non interface used as a constraint, a method declared on an interface, or a type alias or constant that refers to itself. A common case is t.await(): await is written without parentheses. See core 2.4, 2.7, and 7.1.

Example

fn f() -> Int {
 scope s {
 let t = s.spawn(fn() { 1 })
 t.await()
 }
}

Fix

fn f() -> Int {
 scope s {
 let t = s.spawn(fn() { 1 })
 t.await
 }
}

Run xo explain XO0407 for this text in a terminal, or see section 10.6 of the specification.

XO0408: const initializer is not a compile time value

Mon, 01 Jan 0001 00:00:00 +0000

A const initializer may use only literals, other constants, struct and enum construction, and collection literals of those. Calls and runtime values such as parameters are not compile time values. Use a let binding, or compute the value with a function. See core 3.1.

Example

fn g() -> Int { 1 }

const X = g()

Fix

const X = 1

Run xo explain XO0408 for this text in a terminal, or see section 10.6 of the specification.

XO0409: invalid explicit conversion

Mon, 01 Jan 0001 00:00:00 +0000

Numeric conversions such as Int(x) and Float(x) take a number. Text is not a number: parse it with Int.parse(s), which returns Int?, and decide what a bad input means. See core 2.1.

Example

fn f(s: Str) -> Int { Int(s) }

Fix

fn f(s: Str) -> Int { Int.parse(s) ?? 0 }

Run xo explain XO0409 for this text in a terminal, or see section 10.6 of the specification.

XO0410: reading a Map by index; use `get` or `get_or_fault`

Mon, 01 Jan 0001 00:00:00 +0000

A missing key is the Map form of a nil dereference, so m[k] in an expression, or an in place change through it (m[k].f = v, m[k] += 1), is an error. Use m.get(k) (an optional), m.get_or_fault(k, "why the key must exist"), or m.update(k, init, fn(var v) { ... }). On a var map the whole value assignment m[k] = v is allowed and means m.put(k, v). See core 3.6.

XO0420: constant std/time layout is invalid

Mon, 01 Jan 0001 00:00:00 +0000

A layout passed to time.format, time.parse, or time.check_layout is written with named, lowercase fields: {year}, {month} (also {month:1}, {month:short}, {month:name}), {day} ({day:1}), {weekday:short}, {weekday:name}, {hour}, {hour12} with {ampm}, {minute}, {second}, {frac} ({frac:1} to {frac:9}), {offset} ({offset:compact}), {zone}, and {lbrace}/{rbrace} for literal braces (std.md 13.3). When the layout is a constant (a string literal, a const, or a + of them) the checker parses it: an unknown field, a field form that does not exist, a stray brace, or {hour12} without {ampm} is this error, with a did you mean fix for a misspelled field. Date patterns of other languages ({yyyy}, yyyy-MM-dd, %Y-%m-%d, Go’s 2006-01-02) are the habit XO0177 instead, with a fix to the named fields. A layout built at run time is not checked here: format and parse fault on a bad one, and time.check_layout returns a Result for layouts that come from input. See decision 0094.

XO0501: var method called on a non var binding

Mon, 01 Jan 0001 00:00:00 +0000

A method with a var receiver (including mutating collection methods such as push and put) changes the caller’s binding in place. It can be called only on a var binding, a var parameter, or a field of one. A Mutex.with closure parameter declared without var is a read only view. Declare the binding with var (the diagnostic offers that fix). See core 3.4 and 5.2.

Example

fn f() -> List[Int] {
 let xs = [1]
 xs.push(2)
 xs
}

Fix

fn f() -> List[Int] {
 var xs = [1]
 xs.push(2)
 xs
}

Run xo explain XO0501 for this text in a terminal, or see section 10.6 of the specification.

XO0502: assignment to an immutable binding or to a captured variable

Mon, 01 Jan 0001 00:00:00 +0000

Only var bindings, var parameters, var receivers, and their fields and elements can be assigned or passed to a var parameter. let, constants, pattern bindings, and for bindings are immutable. Closures capture by value, so mutating a captured var inside a closure is also an error; share state through a Mutex or Atomic instead. See core 3.3 and 5.2.

Example

fn f() -> Int {
 let x = 1
 x = 2
 x
}

Fix

fn f() -> Int {
 var x = 1
 x = 2
 x
}

Run xo explain XO0502 for this text in a terminal, or see section 10.6 of the specification.

XO0503: one variable or overlapping places passed to two `var` parameters of one call

Mon, 01 Jan 0001 00:00:00 +0000

A call may not pass the same variable, or two places that overlap (x and x.f, xs[i] and xs[j] unless both indexes are different literals, a var receiver and an argument naming it), to two var parameters. The Go backend passes var arguments by reference and the native backends copy them in and out, so aliased writes would differ; with aliasing ruled out both conventions give one result. Copy one of the places into a temporary, pass the temporary, and store it back after the call, or take a single var parameter of a struct that holds both values. See core 5.2 and decision 0111.

XO0510: use of a moved Buf, StrBuilder, or BytesBuilder

Mon, 01 Jan 0001 00:00:00 +0000

Buf[T], StrBuilder, and BytesBuilder are mutable in place and move only. freeze(), assigning, passing to a function, sending on a channel, or capturing in a spawned task moves the buffer, and the old name may not be used again (until it is reassigned). Finish all writes before moving, or start a new buffer. See core 5.3.

Example

fn f() -> List[Int] {
 var b = Buf[Int].with_capacity(8)
 b.push(1)
 let xs = b.freeze()
 b.push(2)
 xs
}

Fix

fn f() -> List[Int] {
 var b = Buf[Int].with_capacity(8)
 b.push(1)
 b.push(2)
 b.freeze()
}

Run xo explain XO0510 for this text in a terminal, or see section 10.6 of the specification.

XO0520: mutation of a copied or stored collection element is never written back

Mon, 01 Jan 0001 00:00:00 +0000

Xo collections hold values, not references. A local var initialized from a collection element (m.get(k), m[k], xs[i], first, find, optionally with ??, ?, or .or_err(...)?) and then mutated changes only the copy; the collection keeps the old value. The same holds for a var mutated after being pushed or put into a collection. Store it again (m.put(k, b)), or use m.update(k, init, fn(var b) { ... }). Reading or returning the copy does not count as storing. See core 5.2.

XO0601: name does not resolve

Mon, 01 Jan 0001 00:00:00 +0000

A variable, function, type, field, method, module, or effect name does not exist where it is used. The diagnostic suggests the nearest real names, so an API cannot be hallucinated silently. It also covers os, expect, and testing outside tests, a tuple field out of range, and result outside an ensures clause. Float.from(n) and other unknown associated functions of a numeric type called with one numeric argument get the fix Float(n): numeric conversions are calls on the type name (std.md 2.1). See core 4.3.

XO0602: import path does not yield a valid local name

Mon, 01 Jan 0001 00:00:00 +0000

An import binds its last path segment as the local name, with - replaced by _. For a Go package the local name is the Go package name. If the result is still not a valid identifier, or is a keyword, give the import a name with as. See core 4.1.

Example

// main/main.xo, with a module directory 03-lib
use example.com/app/03-lib

fn f() -> Int { 1 }

Fix

use example.com/app/03-lib as lib

fn f() -> Int { lib.one() }

Run xo explain XO0602 for this text in a terminal, or see section 10.6 of the specification.

XO0603: name declared twice in one scope, or a predeclared name redefined

Mon, 01 Jan 0001 00:00:00 +0000

A name may be declared once per scope: top level declarations, fields, variants, methods, parameters, imports, and bindings in one block. Shadowing is allowed only in a nested block. Predeclared names (Option, Result, true, dbg, builtin types, …) cannot be redefined at top level, and a type cannot have a field and a method with the same name. See core 1.4 and 3.1.

Example

fn f() -> Int {
 let x = 1
 let x = 2
 x
}

Fix

fn f() -> Int {
 let x = 1
 let y = 2
 x + y
}

Run xo explain XO0603 for this text in a terminal, or see section 10.6 of the specification.

XO0604: cyclic module imports

Mon, 01 Jan 0001 00:00:00 +0000

Modules may not import each other in a cycle, so every module can be checked and built after its dependencies. Move the shared declarations into a third module that both import, or merge the two modules. See core 4.1.

Example

// a/a.xo
use example.com/app/b

pub fn fa() -> Int { b.fb() }

// b/b.xo
use example.com/app/a

pub fn fb() -> Int { 1 }
pub fn g() -> Int { a.fa() }

Fix

// a/a.xo
use example.com/app/b

pub fn fa() -> Int { b.fb() }

// b/b.xo (no longer imports a)
pub fn fb() -> Int { 1 }

Run xo explain XO0604 for this text in a terminal, or see section 10.6 of the specification.

XO0605: name is not `pub` in its module, or the std type is an opaque handle

Mon, 01 Jan 0001 00:00:00 +0000

Only pub declarations, fields, and methods are visible outside their module. Mark the declaration pub if it is part of the module’s API, or use an exported function instead. Some std types are opaque handles with no visible fields; they cannot be built with a struct literal and are created by their constructor function. See core 1.5.

Example

// lib/a.xo
fn hidden() -> Int { 1 }

// main/main.xo
use example.com/app/lib

fn f() -> Int { lib.hidden() }

Fix

// lib/a.xo
pub fn hidden() -> Int { 1 }

// main/main.xo
use example.com/app/lib

fn f() -> Int { lib.hidden() }

Run xo explain XO0605 for this text in a terminal, or see section 10.6 of the specification.

XO0606: method declared outside the module of its type

Mon, 01 Jan 0001 00:00:00 +0000

Methods may be declared only in the module that declares the type, so a type’s method set is fixed by its owner and two modules cannot add conflicting methods. For a builtin or imported type, write a plain function instead. See core 3.4.

Example

fn (s: Str) shout() -> Str { s.to_upper() }

Fix

fn shout(s: Str) -> Str { s.to_upper() }

Run xo explain XO0606 for this text in a terminal, or see section 10.6 of the specification.

XO0607: `break` or `continue` outside a loop, or an unknown label

Mon, 01 Jan 0001 00:00:00 +0000

break and continue must be inside a loop of the same function or closure, and a label must name an enclosing labeled loop (outer: for ... { break outer }). Inside a closure, return leaves the closure; a loop outside it cannot be broken from inside. See core 3.5.

Example

fn f(xs: List[Int]) {
 for _x in xs {
 break outr
 }
}

Fix

fn f(xs: List[Int]) {
 outer: for _x in xs {
 break outer
 }
}

Run xo explain XO0607 for this text in a terminal, or see section 10.6 of the specification.

XO0701: effect performed outside the declared set

Mon, 01 Jan 0001 00:00:00 +0000

pub functions, interface methods, function types, and any function with a uses clause are checked against their declared effects; no clause means pure. Performing an effect outside that set, directly or through a call chain, a closure, an interface implementation, or a Go call (effect go), is an error, and the diagnostic shows the chain that performs it. Contract clauses (requires, ensures, invariant) must be pure. Declare the effect, or pass the work in from a caller that has it. See core 6.2.

XO0702: unknown effect label

Mon, 01 Jan 0001 00:00:00 +0000

Effect labels are net (net.dial, net.listen), fs (fs.read, fs.write), clock, rand, env, proc, stdio, ffi, and go for calls into Go packages, plus effect variables declared as fx: Effects. Any other name in a uses clause or effect argument is an error, as is an effect argument that is not a label, variable, or parenthesized list of them. See core 6.1.

Example

pub fn g() uses network {}

Fix

pub fn g() uses net {}

Run xo explain XO0702 for this text in a terminal, or see section 10.6 of the specification.

XO0703: effect declared in `uses` is never performed

Mon, 01 Jan 0001 00:00:00 +0000

Reported by xo vet as a warning, never by xo check. Declaring more effects than the body performs is allowed, for example to keep an interface or a pub API stable while its implementation changes (core 6.2). Unless that is the intent, the extra effect overstates what the function can do and forces callers to declare it too. Remove it, or keep it deliberately.

Example

pub fn now(c: Clock) -> Time uses clock, net {
 c.now()
}

Fix

pub fn now(c: Clock) -> Time uses clock {
 c.now()
}

Run xo explain XO0703 for this text in a terminal, or see section 10.6 of the specification.

XO0801: child or group task error does not convert to the enclosing error type

Mon, 01 Jan 0001 00:00:00 +0000

If a task fails with an error that no await consumes, the scope cancels everything else and the error propagates out of the scope as if by ?, so it must convert to the enclosing function’s error type. The same holds for tasks on a task group. When the group or scope handle came from outside the function, a task started on it must not fail unless its handle is bound and awaited. Bind the handle and handle t.await, handle the error inside the task, or declare a compatible error type. See core 7.1.

XO0802: scope handle, or a value containing a task group, escapes its scope

Mon, 01 Jan 0001 00:00:00 +0000

No task outlives its scope. A scope handle, a closure that captures one, or a value whose type contains a task.Group from s.group() cannot be the scope’s value, be returned, or be stored outside the scope (in an outer var, a collection, or a channel), because it could start tasks after the scope ended. os.tasks, the program lifetime group from main, may be stored anywhere. See core 7.1.

Example

fn f() -> Int {
 let h = scope s { s }
 1
}

Fix

fn f() -> Int {
 scope s {
 let t = s.spawn(fn() { 1 })
 t.await
 }
}

Run xo explain XO0802 for this text in a terminal, or see section 10.6 of the specification.

XO0803: task started without a scope handle

Mon, 01 Jan 0001 00:00:00 +0000

Xo has structured concurrency only: tasks are started with s.spawn(f) or s.spawn_background(f) on a scope handle inside scope s { ... }, or on a task group, so every task belongs to a scope that waits for it. There is no free spawn or go statement, and spawn on a value that is not a scope handle or group is an error. See core 7.1.

Example

fn work() {}

fn f() {
 spawn(fn() { work() })
}

Fix

fn work() {}

fn f() {
 scope s {
 s.spawn(fn() { work() })
 }
}

Run xo explain XO0803 for this text in a terminal, or see section 10.6 of the specification.

XO0804: value read in one `Mutex.with` is written back in a later one

Mon, 01 Jan 0001 00:00:00 +0000

Warning. A value read (or derived) inside one m.with(...) is used inside a later m.with(...) on the same mutex, or a branch on it decides whether the later one runs. Another task may change the state between the two sections (check then act), so the write can overwrite a newer value. Do the read and the write in one with. See core 5.4.

Example

struct B { n: Int }

fn bump(m: Mutex[Map[Str, B]]) {
 let b = m.with(fn(s) { s.get("k") ?? B{n: 0} })
 m.with(fn(var s) { s.put("k", b with {n: b.n + 1}) })
}

Fix

struct B { n: Int }

fn bump(m: Mutex[Map[Str, B]]) {
 m.with(fn(var s) {
 let b = s.get("k") ?? B{n: 0}
 s.put("k", b with {n: b.n + 1})
 })
}

Run xo explain XO0804 for this text in a terminal, or see section 10.6 of the specification.

XO0900: typed hole report

Mon, 01 Jan 0001 00:00:00 +0000

Warning. ??? is a typed hole, valid anywhere an expression is expected. xo check succeeds and reports, for each hole, the expected type, the effects in scope, and in scope values or functions that fit. xo build rejects programs with holes; xo run --holes and xo test --holes allow them and fault if a hole is evaluated. Holes let an agent write a type correct skeleton first and fill it in steps. See core 3.7.

XO0901: `dbg(...)` left in code

Mon, 01 Jan 0001 00:00:00 +0000

Reported by xo vet as a warning. dbg(expr) prints the expression source and its Debug value and returns the value, which is useful while debugging but noise in committed code; xo build --ci rejects it. Remove the call and keep the expression, or log through std/log if the output is meant to stay. See core 11.4.

Example

fn area(w: Int, h: Int) -> Int {
 dbg(w * h)
}

Fix

fn area(w: Int, h: Int) -> Int {
 w * h
}

Run xo explain XO0901 for this text in a terminal, or see section 10.6 of the specification.

XO1001: std/sys/ used outside the matching target arm

Mon, 01 Jan 0001 00:00:00 +0000

Platform specific APIs live in std/sys/<os> and may be referenced only inside the arm of a match target.os for that OS, so code for one platform cannot leak into another’s build while every arm is still type checked on every host. The prototype does not emit this code yet: no std/sys/<os> modules exist, and the example below names a hypothetical std/sys/linux function. See core 12.2.

Example

use std/sys/linux

pub fn page_size() -> Int {
 linux.page_size()
}

Fix

use std/sys/linux

pub fn page_size() -> Int {
 match target.os {
 Linux => linux.page_size()
 Darwin => 16384
 Windows => 4096
 Wasi => 65536
 }
}

Run xo explain XO1001 for this text in a terminal, or see section 10.6 of the specification.

XO1101: Go package cannot be bound

Mon, 01 Jan 0001 00:00:00 +0000

use go "path" generates a binding for the Go package (into .xo/gobind/ or $XO_GOBIND_DIR). This failed: the package was not found by Go’s module resolution, does not build, is a main package, or the binding generator reported an error (the message carries Go’s reason). Check the import path and that the module is available to the Go toolchain; xo bind <path> runs the binding step alone. See core 4.4 and decision 0041.

XO1102: Go name exists but its signature does not map to Xo

Mon, 01 Jan 0001 00:00:00 +0000

The Go package exports this function, method, or type, but its signature uses something the binding cannot express in Xo (for example complex numbers, channels, or unsafe pointers), so the binding skipped it. Skipped names and their reasons are listed at the top of the generated binding. Use another function, or write a small Go wrapper with a mappable signature. A name that does not exist at all is XO0601 instead. See core 4.4.

XO1103: per module report of `use go` packages and the functions that perform `go`

Mon, 01 Jan 0001 00:00:00 +0000

Reported by xo vet as a note, once per module. Go code can reach files and the network without a capability, so every call into Go performs the effect go, and agents may reach for Go idioms through the boundary out of habit (decision 0041). The note lists the Go packages the module imports and the functions that perform go, so the authority escape can be reviewed. See core 4.4.

XO1104: C header cannot be bound

Mon, 01 Jan 0001 00:00:00 +0000

use c "header.h" reads the header with clang’s AST dump and generates an Xo declaration file and a C adapter (into .xo/cbind/ or $XO_CBIND_DIR). This failed: the header is neither a file relative to the module directory nor on the C include path, clang reported an error in it, a link file does not exist, or the line’s uses names an unknown effect. The message carries the reason. link "x.c" (or .a, .o) is a path relative to the module directory; link "z" (no extension or /) links the library -lz. xo bind --c <header> runs the binding step alone. See core 4.4 and decision 0116.

XO1105: C function exists in the header but its signature does not map to Xo

Mon, 01 Jan 0001 00:00:00 +0000

The header declares this function, but a parameter or the result is a type the boundary does not carry (decision 0093): an output pointer, a mutable buffer, a char * result whose owner is unknown, a pointer to a struct the header defines, a function pointer, an array, or a variadic list. The binding maps scalars, const char * (Str), a const byte pointer followed by an integer length (Str or Bytes), flat structs of scalars (copied), and pointers to structs the header leaves undefined (opaque handles). Skipped names and their reasons are listed at the top of the generated binding. Write a small C wrapper with a mappable signature, declare it in a header of your module, and bind that header. See core 4.4 and decision 0116.

XO1201: not available without a garbage collector

Mon, 01 Jan 0001 00:00:00 +0000

xo build --no-gc (also xo run, xo test, and xo check) selects a native backend (arm64 on arm64 hosts, LLVM otherwise), whose memory is reference counted instead of collected. Before any code is generated, a check reports every construct, std API, or effect the native backends do not support, at the call site, naming the feature. The message says whether support is planned (the program will build once the native backends grow it; until then build without --no-gc) or impossible: code from a use go package needs Go’s runtime and garbage collector, so it can never run in a native build. The check is derived from what the native code generator supports, so a program it accepts builds. See core 10.1 and decision 0083.

XO1301: malformed xo.mod require, xo.lock, or xo.work line

Mon, 01 Jan 0001 00:00:00 +0000

A require line of xo.mod is require <module path> <version>: the module path is its git location (its first element is a host name) and the version a tag vX.Y.Z. A module is required once. xo.mod has no replace, exclude, or retract; local code is reached through an xo.work workspace. xo.lock lines are <module path> <version>[/xo.mod] h1:<hash> and are written by xo get and xo mod tidy. xo.work lines are xo <edition> and use <dir>, each dir holding an xo.mod. See core 4.2, 4.3, and decision 0086.

XO1302: module version cannot be fetched

Mon, 01 Jan 0001 00:00:00 +0000

A module path is its location: github.com/acme/billing is fetched with git from https://github.com/acme/billing.git (XO_GIT_BASE=<dir or URL> or XO_GIT_REWRITE=<prefix>=<url>,… point it elsewhere, for mirrors and tests), and version v1.4.0 is the tree of the tag v1.4.0, extracted with git archive (no code runs). A module in a subdirectory of its repository (github.com/acme/tools/cli in cli/) is that directory’s tree at the tag cli/v1.4.0. This failed: the repository cannot be reached or cloned, it has no such tag, the tag has no xo.mod in the module’s directory, or that xo.mod declares a different module path. The message carries git’s reason. With XO_PROXY listing module proxies, the message carries each source’s answer: a proxy that does not have the version (404) passes on to the next source after a comma, any error does after a pipe, and off forbids fetching. A zip with paths outside the module, or a tree that contradicts the proxy’s own .lock answer, also fails here. See core 4.2 and decisions 0086 and 0126.

XO1303: module version not in the cache while offline

Mon, 01 Jan 0001 00:00:00 +0000

With XO_OFFLINE=1 or --offline, the toolchain never touches the network: every required module version must already be in the module cache ($XO_MODCACHE, default <user cache dir>/xo/mod) or in the main module’s vendor/. This version is in neither. Fetch it once while online (xo mod tidy, xo get <path>@<version>, or any build), or commit a vendor/ directory with xo vendor. See core 4.2 and decision 0086.

Example

XO_OFFLINE=1 xo build . # billing v1.4.0 was never fetched

Fix

xo mod tidy # online, once
XO_OFFLINE=1 xo build . # from the cache from now on

Run xo explain XO1303 for this text in a terminal, or see section 10.6 of the specification.

XO1304: module content does not match xo.lock

Mon, 01 Jan 0001 00:00:00 +0000

xo.lock records the content hash of every module version the build uses (and of the xo.mod of every version minimal version selection read); every build recomputes them from the cache or vendor/ and compares. A mismatch means the code changed under the same version: a tag was moved or rewritten upstream, or a cached or vendored copy was edited. Nothing is built. If the new content is expected (you control the dependency and retagged it), delete its lines from xo.lock and run xo mod tidy; for an edited vendor/, run xo vendor. See core 4.3.

XO1305: xo.lock has no hash for a module version

Mon, 01 Jan 0001 00:00:00 +0000

Every module version the build selects must be recorded in xo.lock, so the content of a build is pinned and checked. A require line was added or changed by hand, or a dependency upgrade raised the version of a module further down the graph. xo mod tidy (or xo get) records the hashes; commit xo.lock with xo.mod. See core 4.3 and decision 0086.

Example

// xo.mod edited by hand, xo.lock not updated
require github.com/acme/billing v1.5.0

Fix

xo mod tidy # writes the v1.5.0 hashes to xo.lock

Run xo explain XO1305 for this text in a terminal, or see section 10.6 of the specification.

XO1306: import from a module xo.mod does not require

Mon, 01 Jan 0001 00:00:00 +0000

An import path whose first element is a host name (github.com/acme/billing/invoice) names a package of another module, and that module must be required in xo.mod so its version is selected and locked. xo get <module path> adds the latest version; xo mod tidy adds a requirement for every such import. See core 4.1, 4.2, and decision 0086.

Example

use github.com/acme/billing/invoice // xo.mod has no require for it

fn total() -> Int { invoice.total() }

Fix

// xo get github.com/acme/billing adds to xo.mod:
require github.com/acme/billing v1.4.0

Run xo explain XO1306 for this text in a terminal, or see section 10.6 of the specification.

XO1307: vendor/ does not match xo.mod

Mon, 01 Jan 0001 00:00:00 +0000

When the main module has vendor/modules.txt, builds use vendor/ only: no module cache, no network. Every requirement of xo.mod must then be vendored at its version (or above, as minimal version selection chose), and vendor/ must be readable. xo.mod changed since the last xo vendor; run it again. A vendored tree that was edited is XO1304 instead. See core 4.2 and decision 0086.

Example

// xo.mod now requires v1.5.0, vendor/modules.txt still lists
# github.com/acme/billing v1.4.0

Fix

xo mod tidy
xo vendor

Run xo explain XO1307 for this text in a terminal, or see section 10.6 of the specification.

XO1308: release build while a workspace overrides modules

Mon, 01 Jan 0001 00:00:00 +0000

An xo.work workspace builds the modules it uses from their local directories, overriding the versions xo.mod requires. That is for development only: a release build (xo build --release, and xo build --ci) must build exactly what xo.mod and xo.lock pin, so it fails while a workspace overrides a required module, naming those modules. Build with --workspace=off (or XO_WORK=off) to ignore xo.work, or release the overridden modules, require their new versions, and run xo mod tidy. See decision 0086.

XO1309: call into a dependency above its effect ceiling

Mon, 01 Jan 0001 00:00:00 +0000

A uses clause after a require’s version in xo.mod (require github.com/acme/billing v1.4.0 uses none) is the effect ceiling of that dependency: every call from this module into it, and every use of one of its functions as a value, may perform only the effects listed (uses none: none; fs admits fs.read). The effects counted are those the dependency’s function declares itself, not the effects of callbacks you pass it. A use <dir> uses ... line of xo.work sets a ceiling for calls from the other workspace modules. The error sits on the call, so an upgrade whose new version adds an effect fails where it matters. Review why the dependency now needs the effect; then raise the ceiling, or stay on a version within it. See core 4.2 and decision 0086.

XO1310: breaking change in a minor or patch release

Mon, 01 Jan 0001 00:00:00 +0000

xo publish compares the exported API and effects of the module (the declarations xo query api lists, in every package of the module) with the previous vX.Y.Z tag. A minor or patch release may add exports but must not remove one, change its signature, or add an effect to a function (callers’ effect ceilings and uses clauses would break). A breaking change needs a new major version, whose module path ends in /vN from v2 on; before v1.0.0 (v0.x.y), a minor bump may break and a patch may not. Each breaking change is listed with the old and new signature. See decision 0086.

XO1311: the release cannot be made

Mon, 01 Jan 0001 00:00:00 +0000

Publishing a module version is creating its git tag; xo publish validates first and prints the tag command, it never pushes. It needs the module in a git repository (at its root, or in a subdirectory whose name ends the module path, tagged <dir>/vX.Y.Z), no uncommitted changes (without –check), a version tag that does not exist yet and is above the last release, a major version that matches the module path (/vN from v2 on), and an xo.mod and xo.lock that load. See decision 0086.

XO1312: import forbidden by a deny rule

Mon, 01 Jan 0001 00:00:00 +0000

A deny <package> -> <package>, ... line of xo.mod is an import direction rule: a package matching the left side may not use a package matching any pattern on the right. A pattern is a package path, or a path ending in /... that matches it and every package under it. Each direct use is checked, whether or not it is used, so a chain of imports is caught at its first forbidden step. The rules of the main module (and of each workspace module) apply to its own packages. There is no machine fix: removing an import is a design change. Move the code the package needs to a package it may import (often an interface or a plain data type in the lower layer), or change the rule if the architecture changed. xo query imports <pkg> lists the imports of a package with the use line of each. See core 4.2 and decision 0095.

XO1313: fetched module version disagrees with the checksum log

Mon, 01 Jan 0001 00:00:00 +0000

With XO_SUMDB naming a checksum log (<name>+<key id>+<public key> [<URL>]), the first fetch of every module version (from git or a proxy) is checked against the log before it enters the module cache: the log’s record of the version must hold the same tree and xo.mod hashes, the record must be in the tree the log signed (an inclusion proof), the tree head must carry a valid signature by the configured key, and the tree must extend every tree this module cache saw from the log before (a consistency proof). Any failure means someone is serving different content for the same version (a moved tag, a tampered proxy or mirror) or the log itself forked or rewrote history. Nothing is cached or built. Find out which source changed before trusting it. A private module that the log can never see belongs in XO_NOSUMDB. See core 4.3 and decision 0124.

XO1314: module fetch settings malformed, or the checksum log unreachable

Mon, 01 Jan 0001 00:00:00 +0000

XO_PROXY is a list of proxy URLs (http or https), direct (git), and off, separated by commas (try the next source only after “not found”) or pipes (after any error); the default is direct. XO_NOPROXY and XO_NOSUMDB are comma separated path patterns (github.com/acme/*, *.corp.example.com). XO_SUMDB is off (the default) or a log’s verifier key and optional URL. This code is reported when one of them cannot be parsed, or when the checksum log could not be consulted for a first fetch (unreachable, no record of the version, malformed answers): the version is not cached rather than cached unverified. A log that answers but contradicts the fetched content is XO1313 instead. See decisions 0124 and 0126.

XO1401: allocation in a real-time function

Mon, 01 Jan 0001 00:00:00 +0000

A function declared uses realtime (core 6.5) may not allocate: list, map, and set literals, string interpolation, + and += on Str, List, or Bytes, slicing, closures, storing into a Map, and every prelude method that builds a new collection or Str or grows one (push, put, insert, sort, map, …). Allocate during initialization instead (in code that is not real-time), and write preallocated Lists by index: xs[i] = v is in place when the List is unique. The message of fault(...) is exempt, since a fault ends the real-time section. Native builds also count allocations at run time and fault with XO-F007 when a section allocated (a shared List copied on write). See decision 0133.

XO1402: loop without a provable bound

Mon, 01 Jan 0001 00:00:00 +0000

Every loop of a real-time function (core 6.5) needs a bound known at compile time: a for over a range whose ends are constants is bounded by its length; any other for and every while needs a bound N clause after the iterated value or the condition, N a constant Int. A bound is a contract (core 3.5): when the iteration count is not constant, the loop faults with XO-F006 when it would start iteration N + 1, and xo test fuzzes the function. This code is also reported in any function when a bound is not a constant, is negative, or is smaller than a constant range it bounds.

XO1403: call of a function not known to be real-time

Mon, 01 Jan 0001 00:00:00 +0000

A real-time function (core 6.5) may call only other real-time functions (declared uses realtime), the bounded prelude methods (scalar arithmetic, len, get, contains, List.set, Atomic operations), and C functions of a use c module. A call of a function value or of an interface method (a capability, or a method of a type parameter’s constraint) is rejected: its callee is not known, so neither its allocation nor its recursion can be checked. Mark the helper uses realtime when it follows the rules, or move the call out of the real-time function.

XO1404: recursion among real-time functions

Mon, 01 Jan 0001 00:00:00 +0000

The call graph of real-time functions (core 6.5) must be acyclic, so that their stack depth is bounded. A function that calls itself, directly or through other real-time functions, is reported at the call that closes the cycle. Since real-time functions cannot call function values or interface methods, recursion through them is ruled out too. Rewrite the recursion as a loop with bound N and an explicit stack in a preallocated List.

XO1405: blocking operation in a real-time function

Mon, 01 Jan 0001 00:00:00 +0000

A real-time function (core 6.5) may not wait for other tasks or the operating system: channel operations, for over a channel, Mutex.with and with_read, scope, select, spawning and awaiting tasks, dbg, and capability calls are rejected. It may declare no effect besides ffi. Atomic operations do not block and are allowed: share state with the rest of the program through Atomic values, or pass the data in and out as arguments.