Skip to content

Exceptions

FieldStruct has only three exception classes of its own. Bad input is normally recorded on errors, not raised, and the three classes below are for the cases where raising is the whole point. Everything else is a standard Ruby error whose message is a full sentence and never includes an input value.

StandardError
FieldStruct::Error
FieldStruct::CoercionError #field_name, #original
FieldStruct::ImmutableError
FieldStruct::UnknownAttributeError #keys

One rescue FieldStruct::Error catches all three.

A setter raises it when a type can’t read a value and the effective coercion policy is :raise. The previous value stays in place.

Reader Value
message could not coerce <InputClass> input for <field>: <reason>
field_name the field, as a Symbol
original the exception the type raised. It is also the cause

Through new, assign_attributes and with, the first bad key raises. For arrays the message includes an index phrase like element at index 1: .... The reason names classes, never values.

class Anemometer < FieldStruct::Base
coercion_policy :raise
required :gust_kph, :float
optional :calibrated_on, :date
end
begin
Anemometer.new(gust_kph: 'breezy')
rescue FieldStruct::CoercionError => e
e.field_name # => :gust_kph
e.original.class # => ArgumentError
e.cause.equal?(e.original) # => true
e.message.start_with?('could not coerce String input for gust_kph:') # => true
end
vane = Anemometer.new(gust_kph: 35)
begin
vane.calibrated_on = 'last spring'
rescue FieldStruct::CoercionError => e
e.field_name # => :calibrated_on
end
vane.calibrated_on # => nil

Any setter, and assign_attributes, raises it on an instance of an immutable! class after new has finished, before any coercion happens. The message is <Class> is immutable; cannot reassign <field>, and an anonymous class prints as #<Class:0x...>.

class Benchmark < FieldStruct::Base
immutable!
required :elevation_m, :integer
end
begin
Benchmark.new(elevation_m: 120).assign_attributes(elevation_m: 125)
rescue FieldStruct::ImmutableError => e
e.message # => "Benchmark is immutable; cannot reassign elevation_m"
end

new, assign_attributes and with raise it on a class declared with unknown_attributes :raise, before anything is assigned. keys holds the unknown keys as Symbols in input order, and the message reads unknown attribute(s) for <Class>: :a, :b.

class Seedbed < FieldStruct::Base
unknown_attributes :raise
required :label, :string
end
begin
Seedbed.new(label: 'north', soil: 'clay', shade: 2)
rescue FieldStruct::UnknownAttributeError => e
e.keys # => [:soil, :shade]
e.message # => "unknown attribute(s) for Seedbed: :soil, :shade"
end
Class When
ArgumentError new or assign_attributes given something other than a Hash or to_hash object; with given a positional argument; a declaration problem (bad option value, an option on the wrong type, a reserved name, a bad zone:, an unknown preset); an unknown class macro value; from_json given a root that is not an object; the RBS and Scaffold helpers given bad input; serialize naming an undeclared field; a mirror that can’t read its source; partial or register_option refusing (below)
KeyError an unknown type name, at declaration
NameError use_alias! when the constant already exists and is something else
FrozenError a setter on an instance made with frozen!
NotImplementedError a custom type without coerce or ruby_type
EncodingError from_json given malformed JSON. This is the class Oj raises, and FieldStruct defines none of its own

Declaration problems raise while the class body runs, never at first use, so a typo in a type name or an option value fails at load time. That includes a misspelled option key: requird: true raises unknown option requird: ... (did you mean required:?). The declaration messages are listed on Fields and options.

A few of those ArgumentError messages, from the call or declaration that raises them:

Situation Message
a mirror! class reads an object that lacks a public reader for one of its fields LampView mirrors Bulb, but Bulb has no public reader for :watts
an array of mirrors reads a lazy collection (one that answers first) and has no max_items: set max_items: on Hall#lamps, or load the relation yourself
Klass.partial when Klass::Partial is already defined Kiosk::Partial is already defined; Kiosk.partial would replace it
FieldStruct.register_option for a name registered with another type: or owner: catalog: is already registered by atlas_app (type Hash); register it again only with the same type: and owner:
FieldStruct.register_option for a built-in option default: is a universal field option, so it can't be registered, or length: is a native option of String, ...
an unknown option key unknown option defualt: on field :slot (did you mean default:?)
an adapter’s key before its require unknown option avro: on Booth#slot; avro: is registered by field_struct-avro, so require 'field_struct/avro' before declaring the field

The messages from new and with name the class and the class of the input, never its value:

begin
Seedbed.new(%w[north south])
rescue ArgumentError => e
e.message # => "Seedbed.new expects a Hash (or an object responding to #to_hash), got Array"
end
begin
Class.new(FieldStruct::Base) { required :species, :stirng }
rescue KeyError => e
e.message # => "no FieldStruct type registered for :stirng (did you mean :string?)"
end
begin
Seedbed.new(label: 'east').freeze.label = 'west'
rescue FrozenError
:frozen # => :frozen
end

Each of these lands on errors and leaves the object usable:

  • a missing required field: "is required"
  • a failed format:, enum: or in:: "is invalid"
  • a value a type cannot read under :keep_raw or :replace: "could not be coerced: ..."
  • a failed cross-field validator

Exceptions from your own validators or from a callable default propagate unchanged. So do errors raised while building a nested struct (UnknownAttributeError, CoercionError, ArgumentError): they come through as they are, and the parent’s policy doesn’t handle them.

FieldStruct, Actionable and their adapters are open source under the MIT license.