Skip to content
Arne K. (TRC-Loop) edited this page Nov 14, 2026 · 4 revisions

Errors

rustyon returns typed errors, in the style of encoding/json. Use errors.As to inspect them. All error messages start with rustyon: .

Error Returned by When
*SyntaxError Parse, ParseDocument, Unmarshal, Decoder.Decode, Format, FormatIndent, ParseEditable, ronjson.ToJSON the input is not valid RON
*UnmarshalTypeError Unmarshal, Decoder.Decode, FromValue a RON value does not fit the Go type
*UnknownFieldError Decoder.Decode with DisallowUnknownFields the input has a field the Go struct lacks
*InvalidUnmarshalError Unmarshal, Decoder.Decode, FromValue the target is not a non-nil pointer
*UnsupportedTypeError Marshal, MarshalIndent, Encoder.Encode, ToValue the Go type has no RON form
*UnsupportedValueError Marshal, MarshalIndent, Encoder.Encode, ToValue the Go value cannot be encoded
*MarshalerError Marshal, MarshalIndent, Encoder.Encode, ToValue a MarshalRON or MarshalText method failed

Errors from an io.Reader or io.Writer, and errors returned by your own UnmarshalRON or UnmarshalText methods, are passed through unchanged. Decoder.Decode returns io.EOF when there are no more values.

SyntaxError

type SyntaxError struct {
    Msg string
    Pos Position
}

type Position struct {
    Offset int // 0-based byte offset
    Line   int // 1-based
    Column int // 1-based, counts Unicode code points
}

Position.String() returns line:column.

_, err := rustyon.Parse([]byte("[1,\n  ?]"))
fmt.Println(err)
// rustyon: syntax error at 2:3: unexpected character '?'

var se *rustyon.SyntaxError
if errors.As(err, &se) {
    fmt.Println(se.Pos.Line, se.Pos.Column, se.Pos.Offset, se.Pos, se.Msg)
    // 2 3 6 2:3 unexpected character '?'
}

The message text matches the wording of the ron-rs errors where possible, for example unexpected trailing characters, integer out of bounds or unknown escape character. Positions are those of the character where the parser gave up, which is often just after the offending token.

The rustyon CLI prints these errors as file:line:col: message followed by the source line and a caret under the column. You can build the same output from Pos.

More examples are listed on RON Syntax.

Unmarshal and Decoder report syntax errors with the same message and position as Parse, even though they decode without building a tree. When an error is returned, the decode target may already be partially filled in.

UnmarshalTypeError

A map key that is not comparable in Go (for example a list used as a key of a map[any]int) is reported as this error too:

var m map[any]int
fmt.Println(rustyon.Unmarshal([]byte("{[1]: 2}"), &m))
// rustyon: cannot unmarshal list into Go value of type map[interface {}]int: map key is not comparable in Go
type UnmarshalTypeError struct {
    Value string       // description of the RON value, e.g. "string" or "tuple Triangle"
    Type  reflect.Type // Go type that could not hold the value
    Path  string       // path to the value within the document, e.g. "servers[0].port"
    Msg   string       // optional detail
}

Value describes the RON value: a kind such as integer, string, list, struct, None or Some, or a named form such as identifier Insane, tuple Triangle or struct Point.

type Config struct {
    Servers []Server
}

type Server struct {
    Host string
    Port uint16
}

src := `(servers: [(host: "a", port: 80), (host: "b", port: 70000)])`
var c Config
err := rustyon.Unmarshal([]byte(src), &c)
fmt.Println(err)
// rustyon: cannot unmarshal integer into Go value of type uint16 at servers[1].port: integer 70000 overflows

var te *rustyon.UnmarshalTypeError
if errors.As(err, &te) {
    fmt.Printf("value=%q type=%s path=%q msg=%q\n", te.Value, te.Type, te.Path, te.Msg)
    // value="integer" type=uint16 path="servers[1].port" msg="integer 70000 overflows"
}

Path format

The path is built from the RON names of the fields that lead to the value:

Element Written as Example
struct field name, joined with . servers[1].port
list, tuple or array index [i] servers[1]
map entry [key], the key in RON syntax (shortened after 40 characters) ["eu"][0].host
map key itself {key} {key}
enum variant payload (Name) shapes[0].(Circle).radius

The path is empty for an error at the top level.

var m map[string][]Server
fmt.Println(rustyon.Unmarshal([]byte(`{"eu": [(host: 1)]}`), &m))
// rustyon: cannot unmarshal integer into Go value of type string at ["eu"][0].host

var arr [2]int
fmt.Println(rustyon.Unmarshal([]byte(`[1, 2, 3]`), &arr))
// rustyon: cannot unmarshal list into Go value of type [2]int: expected 2 elements, found 3

Typical Msg values: integer N overflows, float overflows, expected N elements, found M, unknown variant "X", expected an enum variant, expected a unit variant, expected a string, map keys must be strings to decode into a struct, interface type is not a registered enum, unsupported Go type.

UnknownFieldError

type UnknownFieldError struct {
    Field string
    Type  reflect.Type
    Path  string
}

Only a Decoder with DisallowUnknownFields() returns it. It applies to struct fields and to string keys of maps decoded into structs.

dec := rustyon.NewDecoder(strings.NewReader(`(servers: [(host: "a", prot: 80)])`))
dec.DisallowUnknownFields()
var c Config
err := dec.Decode(&c)
fmt.Println(err)
// rustyon: unknown field "prot" for type main.Server at servers[0]

var ue *rustyon.UnknownFieldError
if errors.As(err, &ue) {
    fmt.Println(ue.Field, ue.Type, ue.Path) // prot main.Server servers[0]
}

InvalidUnmarshalError

type InvalidUnmarshalError struct {
    Type reflect.Type
}

The decode target must be a non-nil pointer.

var c Config
fmt.Println(rustyon.Unmarshal([]byte(`()`), c))              // rustyon: Unmarshal(non-pointer main.Config)
fmt.Println(rustyon.Unmarshal([]byte(`()`), nil))            // rustyon: Unmarshal(nil)
fmt.Println(rustyon.Unmarshal([]byte(`()`), (*Config)(nil))) // rustyon: Unmarshal(nil *main.Config)

var ie *rustyon.InvalidUnmarshalError
fmt.Println(errors.As(rustyon.Unmarshal([]byte(`()`), c), &ie)) // true

UnsupportedTypeError

type UnsupportedTypeError struct {
    Type reflect.Type
}

Returned for channels, functions and complex numbers.

_, err := rustyon.Marshal(make(chan int))
fmt.Println(err) // rustyon: unsupported type: chan int

var ute *rustyon.UnsupportedTypeError
fmt.Println(errors.As(err, &ute), ute.Type) // true chan int

UnsupportedValueError

type UnsupportedValueError struct {
    Value reflect.Value
    Msg   string
}

Returned when a value of a supported type cannot be encoded:

  • nesting deeper than 1000 levels, usually a pointer cycle;
  • a field, struct or variant name that is not a valid identifier, even in raw form;
  • a value of a unit enum without a registered name.
type Node struct{ Next *Node }
n := &Node{}
n.Next = n
_, err := rustyon.Marshal(n)
fmt.Println(err)
// rustyon: unsupported value: exceeded maximum nesting depth, possibly a cycle

_, err = rustyon.Marshal(struct {
    A int `ron:"has space"`
}{})
fmt.Println(err)
// rustyon: unsupported value: invalid identifier "has space"

var uve *rustyon.UnsupportedValueError
fmt.Println(errors.As(err, &uve)) // true

NaN and infinities are not errors: RON can represent them as NaN, inf and -inf.

MarshalerError

type MarshalerError struct {
    Type   reflect.Type
    Err    error
    Method string // "MarshalRON" or "MarshalText"
}

Wraps an error from a MarshalRON or MarshalText method, or a syntax error in the RON that MarshalRON returned. It supports errors.Unwrap, so errors.Is and errors.As see the original error.

type Broken struct{}

func (Broken) MarshalRON() ([]byte, error) { return nil, errors.New("boom") }

_, err := rustyon.Marshal(Broken{})
fmt.Println(err)
// rustyon: error calling MarshalRON for type main.Broken: boom

var me *rustyon.MarshalerError
fmt.Println(errors.As(err, &me), errors.Unwrap(me)) // true boom

For a failing MarshalText method the message names MarshalText instead.

Panics

Registering enums with invalid arguments panics instead of returning an error, because it is a programming mistake that shows up at program start. See Enums.

Clone this wiki locally