Exception (Error)

Summary of conditions that lead to which exception or return value. Tests align with this list.

Filing / Field (metaclass, init, set)

Condition	Result	Notes
Required fields (id, source, checksum, etc.) missing	FilingRequiredError; errors / fields contain what is missing
Explicit None for a required field	FilingRequiredError
Value with wrong type for a field	FieldValidationError; includes field, expected_type, actual_type
Change an immutable field after init	FieldImmutableError; includes field, current_value, attempt_value
Multiple field validation errors	FilingValidationError or FilingImmutableError; errors / fields list them
Fields with default may be omitted	OK; default used when omitted
Extended class missing required fields	Same exceptions as above

Filing (to_dict / from_dict)

Condition	Result	Notes
from_dict with missing required keys	FilingRequiredError etc.
from_dict with wrong type	FieldValidationError etc.

Collection.add

Condition	Result	Notes
SHA256 of content does not match filing.checksum	CollectionChecksumMismatchError; includes filing_id, actual_checksum, expected_checksum
add again with same id already added	Overwrite allowed: catalog index is skipped, storage is overwritten; returns (filing, path)

Collection.get_filing / get_content / get

Condition	Result	Notes
Non-existent id	get_filing: None; get_content: None; get: (None, None, None) (3rd element is path: str | None)

Catalog.search / Catalog.count

Condition	Result	Notes
expr が Python の bool（例: Field("x") == "a" & Field("y") == "b" の誤った括弧）	CatalogExprTypeError	& / | の優先順位に注意

Locator.resolve

Condition	Result	Notes
Filing cannot be resolved (no path)	LocatorPathResolutionError (raised inside Collection.add)

Exception message format

• Base: FinoFilingException. message includes the prefix "[Fino Filing] ".
• FilingValidationError / FilingImmutableError / FilingRequiredError: str(exception) may include errors as newline-separated lines (spec only guarantees that they are present; exact format is not part of the spec).

See also

• API Reference Overview
• Test coverage and strategy: Test