Reference

Error codes

Every diagnostic Undra raises, from a macro at compile time, from schema validation, from the runtime or from the undra command, has a stable code, a fixed shape and a fix. The link at the end of each message lands on its code below.

How to read one

A diagnostic says what is wrong, why the rule exists and how to fix it. This one is verbatim from the macro test suite:

error[undra::E0004]: callback `Arc<dyn Listener>` cannot be a field of a record or enum (`Listener` is a callback interface)
  = note: a callback is an instance with a lifetime, not a value: it cannot be copied, compared, stored in a record or mirrored from a signal
  = help: keep an id or a record here, and take the callback as a parameter of the method that needs it
  = docs: https://shreypdev.github.io/undra/docs/errors.html#E0004

All codes

Types and shapes#

E0001 unsupported type in a public position#

Raised by macros, schema validation, the Encode/Decode bounds.

unsupported type in a public position (lists the type and the allowed set); includes i128/u128 (the help points at Decimal, Uuid or a String newtype), DateTime<Local> and DateTime<FixedOffset> ("convert to Utc; offsets do not cross"), a type of the uuid, chrono, time, rust_decimal or bytes crate that only that crate has (DateTime<Utc>, OffsetDateTime, TimeDelta, ..) spelled without the matching feature of undra (one error naming the feature), a Lazy<T> that is not a store field, or is inside a Signal, Computed or DerivedList (ADR-043), a DerivedList field without its row type (ADR-039), Handle (no schema type; an object crosses as Arc<T> or &T, ADR-040), Arc<T> of a built-in or an Rc, a Result whose error type is not a #[undra::error] enum, a Ctx parameter that is misplaced (on a method, not first, or &mut), and a type used as a value that cannot cross (an Encode/Decode bound that is not met: a struct without #[undra::api])

E0002 generic parameter, or a generic type spelled with its arguments#

Raised by macros.

generic parameter on a #[undra::api] item that is not a template, on an error enum, object, store, function, method, constructor, port, callback, query or mutation (the text of each says what to write instead: #[undra::api(generic)] and a named instantiation for a data type; generic(T = [Todo, Note]), the list of types, for a function or method, ADR-058); a const parameter, a where clause or a default type parameter ("only type parameters are supported"); a generic type spelled with its arguments (Page<Todo>: declare #[undra::api] pub type TodoPage = Page<Todo>; and write TodoPage); the wrong number of type arguments for a template (ADR-042)

E0003 lifetime in a public signature#

Raised by macros.

lifetime in a public signature

E0004 a trait object, dyn or impl Trait that is not a callback parameter, or a callback where one may not stand (ADR-041)#

Raised by macros, schema validation (a bound the compiler checks).

trait object / dyn / Box<dyn Fn> / closure / function pointer / an impl Trait that is not a stream (declare a #[undra::callback] trait and take Arc<dyn Trait>, ADR-041); a callback (Arc<dyn Trait>) where one may not stand (anywhere but a parameter of a method, constructor or function, alone or in an Option: a return, a field, a signal, a port or query value), with the help of its position; Arc<dyn Trait> of a trait that is not a #[undra::callback] (the CallbackInterface bound, a branded message)

E0005 Result / Stream outside return position#

Raised by macros, schema validation.

Result or Stream outside return position; a Result<impl Stream<Item = Result<T, E1>>, E2> whose two error types differ (ADR-036)

E0006 map key type not allowed#

Raised by macros, schema validation, a bound the compiler checks.

map key type not allowed: String, integers, bool, Uuid and newtypes of those are keys; a float, a Decimal, a record, a collection, and a newtype of one of those are not (the macros assert K: MapKey at every HashMap/BTreeMap key position, ADR-042)

E0007 unsupported item shape or placement of an Undra attribute#

Raised by macros.

unsupported item shape (a unit struct, a tuple struct of two or more fields or none (one field is a newtype), a record without fields, a type alias that does not name an instantiation of a #[undra::api(generic)] type, an empty enum, an impl item that is neither a method nor a constructor, a receiver that is not &self, a store that is not a struct with named fields, the reserved field name __undra_cell, #[undra::port] on an inherent impl, an Undra attribute on the wrong kind of item, #[undra::api] on a method, #[undra::query] or #[undra::mutation] inside an impl block or a port trait, a function whose signature uses Self, a second #[undra::api] impl block for one type). A second impl block is reported by rustc as "the name _undra_error_E0007_<Type>_has_two_undra_api_impl_blocks_merge_them_into_one is defined multiple times": merge the blocks. A query or mutation inside an impl block that is not #[undra::api] cannot be seen by its macro; rustc then reports "macro definition is not supported in traits or impls" and "cannot find macro _undra_error_E0007_a_query_is_a_free_function_move_it_out_of_the_impl_block", which is this code: move the function out of the block

E0008 unknown or misplaced #[undra(..)] attribute or macro argument#

Raised by macros.

unknown or misplaced #[undra(..)] attribute or macro argument (an unknown key, with the nearest name suggested, a value of the wrong kind or a value on a flag, key on a signal that is not a Signal<Vec<T>> or a DerivedList<T> (a keyed Computed is pointed at DerivedList<T>), a DerivedList<T> without key (ADR-039), key naming no field of the list's items (for a generic store: of the row type of one instantiation, at its alias), generic on a type, an impl block or a store that has no type parameter, generic(..) with a list on a struct, an enum or an impl block (a list instantiates a function; a type is instantiated by an alias, ADR-058), generic alone on a function, a malformed list, #[cfg] on a public item, an invalid crate = ".." path); a cfg_attr whose attributes are all documentation or lint levels is accepted

Errors and stores#

E0010 invalid #[undra::error] variant#

Raised by macros, schema validation.

#[undra::error] variant without #[error(..)], a message with an implicit {} (write {0} or {name}), #[error], #[from] or #[source] on a plain #[undra::api] enum

E0011 store and #[undra::api(store)] impl block disagree#

Raised by macros, schema validation.

#[undra::store] and its #[undra::api(store)] impl block disagree, including a store with no impl block and a #[undra::api(store)] block without a constructor (a type takes one block; a constructor in another block is not seen); a store without a constructor in the schema; for a generic store (ADR-058) the impl block below its struct in the same module: a block that is not below a #[undra::store(generic)] struct is reported by rustc as "cannot find macro _undra_error_E0011_<Type>_is_not_a_generic_store_declared_above_this_impl_block_in_the_same_module", a #[undra::store(generic)] whose block is #[undra::api(generic)] without store by a const assertion at the alias, and a #[undra::store(generic)] with no generic block at all by "cannot find macro Selection in this scope ... Selection is in scope, but it is a struct, not a macro": write the block

E0012 trait object in a record field#

Raised by macros.

trait object in a record field (the blueprint example)

E0013 store cannot be restored automatically#

Raised by macros.

store cannot be restored automatically: it has a Computed field, or a field that is neither a signal, a Ctx, a WeakCtx nor Default, and no #[undra::store(restore = "..")] hook

Methods#

E0020 &mut self receiver#

Raised by macros.

&mut self receiver

E0021 self by value#

Raised by macros.

self by value

E0022 non-Send future in an async method: rustc's own error, pointed at the method by an assertion named after this code#

Raised by rustc, named by a macro.

non-Send future in an async method or query: rustc's own "future cannot be sent between threads safely", pointed at the method by an assertion the macros emit; the last note names the assertion, _undra_error_E0022_the_future_of_an_async_method_must_be_Send. Do not hold a non-Send value (an Rc, a RefCell borrow, a MutexGuard) across an .await

The compiler reports this one itself, so it carries no Undra code. It is pointed at the method, and the last note names the assertion the macro emitted, _undra_error_E0022_the_future_of_an_async_method_must_be_Send: the code to look up.

error: future cannot be sent between threads safely
  --> src/lib.rs:15:18
   |
15 |     pub async fn run(&self) -> u32 {
   |                  ^^^ future created by async block is not `Send`
   |
   = help: within `{async block@src/lib.rs:9:1: 9:10}`, the trait `Send` is not implemented for `Rc<u32>`
note: future is not `Send` as this value is used across an await
  --> src/lib.rs:17:32
   |
16 |         let local = Rc::new(1_u32);
   |             ----- has type `Rc<u32>` which is not `Send`
17 |         std::future::ready(()).await;
   |                                ^^^^^ await occurs here, with `local` maybe used later
note: required by a bound in `_undra_error_E0022_the_future_of_an_async_method_must_be_Send`
  --> src/lib.rs:9:1
   |
 9 | #[k::api]
   | ^^^^^^^^^ required by this bound in `_undra_error_E0022_the_future_of_an_async_method_must_be_Send`
   = note: this error originates in the attribute macro `k::api` (in Nightly builds, run with -Z macro-backtrace for more info)

Ports#

E0030 port method with a non-wire parameter#

Raised by macros.

port method with a non-wire parameter

E0031 event port method that is not a plain fn(..) returning ()#

Raised by macros, schema validation.

event port method with a return type, or that is async

E0032 invalid port trait shape#

Raised by macros.

invalid port trait shape (an async method on a sync port, a parameter that is not a plain name, an associated type or const, no &self receiver)

E0033 the error type of a port method has no From<PortError>#

Raised by macros (a bound the compiler checks).

the error type of a Result port method has no From<PortError> (an unavailable port cannot be reported)

Queries and mutations#

E0040 query without key, mutation with stale, or another invalid query argument#

Raised by macros.

query without key / mutation with stale / a query argument of the wrong kind, an interval below one second (use a stream for real-time data), refetch_pages or persist_pages that is not a whole number of at least 1, polling or paging options on a mutation

E0041 query or mutation function with an invalid signature#

Raised by macros.

query or mutation function with an invalid signature (not async, no ctx: &Ctx first parameter, not returning Result<T, E>, a stream result, self)

E0042 query whose success value is () or an Option#

Raised by macros.

query whose success value is () or an Option (a query caches a value; use a mutation for effects)

Names in the generators#

E0050 duplicate type name, id or variant index#

Raised by schema validation.

duplicate type name, a type named like something the generated code depends on, two items with one id, two variants with one index

E0051 a name that collides after case conversion or is not an identifier#

Raised by schema validation.

a name that collides after case conversion (a_b and aB), shadows a member of the runtime base classes, or is not an identifier in a target language; in the iOS 15 / 16 Swift mode also a store member named objectWillChange (§10.1, ADR-045)

E0052 an item named like a standard library item, with another id#

Raised by schema validation.

a record, enum, error, object or port named like a standard library item (section 8) but with another id: the runtimes implement the standard items under those names and ids

Type identity and the schema#

E0060 a spelling that looks like a built-in Undra type is another type#

Raised by macros (a check the compiler runs).

a spelling that looks like a built-in Undra type (Bytes, Uuid, String, Vec, ..) is a different type; reported at the field or parameter by the same-type assertion the macros emit; for a wire leaf (Uuid, Timestamp, Duration, Bytes, Decimal) by the membership assertion Spelled: WireLeaf<kind>, whose message names the leaves and the features (uuid, chrono, time, rust_decimal, bytes) that add the types of other crates (ADR-042)

E0061 the name written is not the declared name of the type, or the type is not declared with #[undra::api]#

Raised by macros (a check the compiler runs).

the schema records a name that the type written there does not have: an alias of an Undra type (type Todo = Item), a renamed import (use m::Item as Todo), or a name that is not a type declared with #[undra::api] at all (a plain struct, type Id = u64); reported by a const assertion on UNDRA_TYPE_ID

E0062 a port call could not be answered and its method has no error channel: a runtime message#

Raised by runtime (the generated port proxy).

a port call that cannot be answered and has no error channel: no adapter registered, a cancelled call, a reply that does not decode. A method without an error channel panics with this message (the runtime contains the panic at the dispatch boundary; on wasm it traps the core); a method returning Result reports it as its error type, and HttpError::Network / FsError::Io carry the code and the link

E0063 nested Option<Option<T>>#

Raised by macros.

Option<Option<T>> in a public position

E0064 an object (#[undra::api] impl) used where a value is expected, or a value used as an object, or an object where objects may not stand (ADR-040)#

Raised by macros (a check the compiler runs), schema validation.

an object (#[undra::api] impl) used as a value (a field, a parameter or a return written Mailbox): it crosses as Arc<Mailbox> or &Mailbox; a record, enum or error written as an object (Arc<Todo>, &Todo: records cross by value); an object where objects may not stand (a record or variant field, a signal, a map key or value, a stream item, a port, callback, query or mutation value, or nested deeper than Option or Vec), with the reason and the way out of its position (ADR-040)

E0065 a signal of a store written off its owning runtime's core (ADR-035): a runtime message#

Raised by runtime (the write check of undra-signals).

a signal of a store was written from a thread that does not hold the owning runtime's core lock: a blocking-pool worker, a host or embedder thread, a thread inside no runtime, or another runtime's core. A panic with this message, in every build; Signal::try_set / try_update return it as WriteError::OffCore (ADR-035)

E0066 a #[undra::migrate] hook with a wrong target or shape (ADR-037; addition)#

Raised by macros, runtime (start-up check of the registered hooks).

a #[undra::migrate] hook with a wrong target or shape (ADR-037): no target or more than one, signal without store, a from that is not a 64-bit hex fingerprint, a function that is not a plain non-generic fn taking the target's old value (&DynValue, Option<&DynValue> or &DynRecord) and returning Result<_, MigrateError>, a ty = "X" hook that does not return the #[undra::api] type X (a const assertion the compiler runs); a store, signal or mutation the core does not have, or a signal hook returning another type than the signal's, is logged at ERROR with this code when a runtime starts (the macro cannot see those items)

E0070 a named instantiation of a generic data type that is declared twice or outside the crate of its template#

Raised by macros (a check the compiler runs).

a named instantiation of a generic data type, object or store (type TodoPage = Page<Todo>, type TodoSelection = Selection<Todo>) declared twice, or outside the crate of its template (ADR-042, ADR-058; for an object or a store a module-level constant _undra_error_E0070_this_instantiation_of_Selection_Todo_is_declared_twice_keep_one_alias_per_instantiation makes a second alias in the same module the first error rustc reports): the inherent impl of the instantiation carries a constant named after the rule (_undra_error_E0070_this_instantiation_of_Page_is_declared_twice_keep_one_alias_per_instantiation), so a second alias of one instantiation is reported by rustc as that constant defined twice; an alias in another crate than its template's is reported by the macro itself, naming both crates

E0071 a method of a #[undra::callback] trait that is neither fire-and-forget nor async with a Result, or whose name starts with __ (ADR-041)#

Raised by macros, schema validation.

a method of a #[undra::callback] trait that returns a value synchronously, is async without a Result, whose name starts with __ (reserved for __release and __cancel), or an async method marked #[undra(coalesce)] (ADR-041): the host runs a callback outside the core's thread and lock, so the core can never wait for it, and a host can always fail or be gone; a method reports (fn m(&self, ..)) or is async and returns Result<T, E>

E0072 the instantiation list of a generic function or method (generic(T = [Todo, Note])) is empty, repeats a type, lists something that is not a named value type, names a type parameter the function does not have, or the function has several type parameters; a schema whose generic labels do not describe their definitions (ADR-058; addition)#

Raised by macros, schema validation.

the instantiation list of a generic function or method (ADR-058): a list for a parameter the function does not have, an empty list, a type listed twice, a type that is not a named value type (Vec<Todo>, a scalar, String, a leaf type, Arc<Mailbox>, an object: a const assertion the compiler runs says so for a plain name that turns out to be an object), a function with two type parameters; in the schema a generic label that does not describe its definition (the name is not of<Type>, the argument is not a record or an enum of the schema, a constructor or port method carries a label) or definitions that share one of but are not one function with one type replaced (a different parameter list, is_async, takes_ctx, inferred flag, parameter name or type shape with the names erased)

E0073 an infinite query that does not meet ADR-043's shape: no item_key or one that names no field of the rows, no or more than one #[undra(cursor)] parameter, a cursor that is not Option<C> or is in the key, a success type that is not Page<T, C>, rows that are not a record#

Raised by macros, schema validation.

an infinite query (ADR-043) that is not a list of records with a cursor: no item_key, or one that names no field of the rows; no or more than one #[undra(cursor)] parameter, a cursor that is not Option<C> or is part of the key; a success type that is not Page<T, C> (with C the cursor's type) or rows that are not a record; item_key, refetch_pages or persist_pages without infinite, persist_pages without persist, #[undra(cursor)] on a query that is not infinite; in the schema an infinite mutation or a returns that is not Vec<T> of a record with the item_key field: the handle shows the pages as one list keyed by a field of its rows, and each page is asked for with the cursor the previous one returned

E0074 the impl block of a generic object that is not for the type with its own type parameters, each exactly once, or a method of a generic object with type parameters of its own (ADR-058; addition)#

Raised by macros.

the impl block of a generic object (ADR-058) that is not for the type with its own type parameters, each exactly once (impl<T> Cache<Vec<T>>, impl<T> Cache<T, Todo>, a parameter applied twice or not at all), or a method of a generic object that has type parameters of its own, with or without a generic(..) list: an instantiation is one class on each platform, and a second level of generics would multiply every one of them

The command line#

C0001 no undra.toml from start up to the filesystem root#

Raised by undra.

not inside an Undra project: no undra.toml from the working directory up to the filesystem root

C0002 a configuration or schema file is unusable#

Raised by undra.

undra.toml or a schema file cannot be read or has a value the CLI cannot use

C0003 a tool is not installed#

Raised by undra.

a tool the command needs is not installed or not on PATH

C0004 a build tool exited with a failure#

Raised by undra.

a build tool ran and failed; its own output follows the diagnostic

C0005 the core crate is missing, or is not an Undra core#

Raised by undra.

the core crate is missing, or is not an Undra core

C0006 the schema could not be extracted from the built core#

Raised by undra.

the schema could not be extracted from the built core

The command prints this diagnostic with the details of the failure that caused it.

C0007 the schema cannot be turned into bindings (bindgen diagnostics)#

Raised by undra.

the schema cannot be turned into bindings (the E0001, E0005, E0006, E0010, E0011, E0031, E0050, E0051, E0052 and E0072 diagnostics of schema validation follow)

C0008 the command would overwrite something it must not#

Raised by undra.

undra init or undra adopt would write into a directory that already has files in it

C0009 an argument is unusable#

Raised by undra.

an argument has a value the command cannot use

C0010 an I/O operation failed#

Raised by undra.

a file or directory operation failed

C0011 the Rust toolchain lacks a compilation target#

Raised by undra.

the Rust toolchain lacks a compilation target the build needs

C0012 the platform is not available on this machine#

Raised by undra.

the platform is not available on this machine

The command prints this diagnostic with the details of the failure that caused it.

C0013 the dev server failed to start or crashed#

Raised by undra.

the dev server failed to start or crashed

The command prints this diagnostic with the details of the failure that caused it.

C0014 the project's Undra does not match: the core's comes from elsewhere, or it is newer#

Raised by undra.

the core and the project disagree about where Undra comes from, or the project is on a newer Undra than this undra (undra upgrade moves a project forward only)

Runtime messages#

The JavaScript runtime (@undra/runtime) throws and logs these. Its production build (what vite build, webpack in production mode and anything else that asks for neither the development nor the react-native condition resolve) says a code, the values and a link instead of a sentence, so a page does not carry the prose of an error whose class, kind and fields it already has: T0017: callSync, remote; see https://shreypdev.github.io/undra/docs/errors.html#T0017. Its development build (Vite's dev server, Vitest, React Native) says the sentence. Both throw the same classes with the same kind and fields; only message differs, so nothing a program can branch on changes. Text the runtime hands on as data, the field of a port's typed error (which the core receives) and a WebSocket close frame's reason (which the peer receives), is not a message: it is the same sentence in both builds. Codes are never reused.

The T codes (166)#

The sentence is what the development build says; {0}, {1}, ... are the values the production message lists, in that order.

Wire failures#

A WireError says its code and fields in a production build (wire: code=unexpected_eof at=12 needed=3; see link); the development build says the sentence below, with the values in braces.

Generated by site/scripts/build-errors.mjs from docs/SPEC.md section 12, the compile-fail tests of the macros crate and the message goldens of the other crates. To change a message, change the code that raises it and regenerate its golden; to change the catalogue, change the specification.

Generated from the specification and the macro tests: edit those, not this page.