Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/iFamishedX/HungerLib/llms.txt

Use this file to discover all available pages before exploring further.

HungerLib defines three distinct exception families: the ValidationError hierarchy for configuration schema problems, HungerLibError subtypes for runtime library errors, and HungerBridgeError for failures returned by the HungerBridge sidecar. Each family has its own base class so you can catch broadly or precisely depending on your needs. 
# Validation exceptions
from hungerlib import ValidationError, FatalError, TypeMismatchError, FallbackError, RecommendedError

# Runtime library exceptions
from hungerlib.utils.exceptions import HungerLibError, InvalidLevelError, InvalidModeError

# Bridge exceptions
from hungerlib.utils.exceptions import HungerBridgeError

​
Validation Exceptions

These exceptions are raised by the Validator class when a configuration schema is checked via Validator.run(). They form a hierarchy rooted at ValidationError so you can choose how broadly to catch them. All ValidationError instances carry structured data about what went wrong, not just a message string. This lets automation scripts inspect individual errors programmatically rather than parsing a string report.

​
ValidationError

The base class for all configuration validation failures. Subclasses indicate the severity and nature of the issue. 
class ValidationError(Exception):
    def __init__(self, report, errors=None, warnings=None, fallbacks=None, recommended=None)
Attributes:
​
report
str
A human-readable multi-line report generated by Validator.format_report(). Contains sections for errors, recommended, fallbacks, and warnings as applicable. Printed automatically when the exception is not caught.
​
errors
list[str]
A list of error message strings describing required fields that are missing or invalid. Empty if no errors were found.
​
warnings
list[str]
A list of warning message strings. Currently reserved for future use by custom Validator subclasses.
​
fallbacks
list[str]
A list of messages describing fields that are present in YAML but whose value matches the fallback default. Raised as FallbackError when non-empty.
​
recommended
list[str]
A list of messages for keys that are absent from the YAML and are considered recommended (not strictly required). Raised as RecommendedError when non-empty.
from hungerlib import ValidationError

try:
    validator.run(config)
except ValidationError as e:
    print(e.report)
    print("Errors:", e.errors)
    print("Warnings:", e.warnings)

​
FatalError

Raised when one or more required configuration fields are missing from the YAML file, or when a required field is set to its fallback value (which is disallowed for "required" fields). Inherits from ValidationError. This is the highest-priority validation exception. Validator.run() raises FatalError as soon as any entry appears in self.errors, before checking for lower-severity issues. 
from hungerlib import FatalError

try:
    validator.run(config)
except FatalError as e:
    print("Configuration is missing required fields:")
    for err in e.errors:
        print(f"  - {err}")
    exit(1)

​
TypeMismatchError

Raised when a YAML value’s Python type does not match the type annotation declared on the corresponding dataclass field. Inherits from ValidationError. In practice, Validator.run() currently raises FatalError before reaching type mismatch checking if self.errors is non-empty. TypeMismatchError is raised independently when type errors are detected without other fatal errors present. 
from hungerlib import TypeMismatchError

try:
    validator.run(config)
except TypeMismatchError as e:
    print("Type mismatch in configuration:")
    for err in e.errors:
        print(f"  - {err}")

​
FallbackError

Raised when a recommended field is present in the YAML file but its value equals the fallback default. This signals that the user has not customised the field. Inherits from ValidationError. 
from hungerlib import FallbackError

try:
    validator.run(config)
except FallbackError as e:
    print("The following fields are using their default fallback values:")
    for msg in e.fallbacks:
        print(f"  - {msg}")

​
RecommendedError

Raised when a key marked as "recommended" in the Validator.rules schema is absent from the YAML file entirely. The field will be populated with its fallback value, but the user is notified that they should set it explicitly. Inherits from ValidationError. 
from hungerlib import RecommendedError

try:
    validator.run(config)
except RecommendedError as e:
    print("Some recommended keys are missing from your config:")
    for msg in e.recommended:
        print(f"  - {msg}")

​
Library Exceptions

These exceptions are raised by HungerLib internals at runtime — not during configuration validation, but during normal operation such as logging or querying server state.

​
HungerLibError

The base class for all HungerLib runtime errors. Catch this to handle any library-originated exception without specifying a subtype. 
from hungerlib.utils.exceptions import HungerLibError

try:
    # any HungerLib operation
    ...
except HungerLibError as e:
    print(f"HungerLib error: {e}")

​
InvalidLevelError

Raised when an unrecognised log level is passed to MessageRouter or to BridgeClient.log(). Valid log levels are defined by MessageRouter’s configured level set. Inherits from HungerLibError. 
from hungerlib.utils.exceptions import InvalidLevelError

try:
    router.log("VERBOSE", "This level does not exist")
except InvalidLevelError as e:
    print(f"Bad log level: {e}")

​
InvalidModeError

Raised when an unrecognised mode string is passed to a method that accepts a mode parameter, such as MinecraftServer.getTPS() or MinecraftServer.getPlayers(). Valid modes are documented on the individual method. Inherits from HungerLibError. 
from hungerlib.utils.exceptions import InvalidModeError

try:
    tps = server.getTPS(mode="invalid_mode")
except InvalidModeError as e:
    print(f"Bad mode: {e}")

​
Bridge Exceptions

​
HungerBridgeError

Raised by BridgeClient when the HungerBridge sidecar returns a non-2xx HTTP response. This indicates a problem on the HungerBridge side — for example, an invalid endpoint, a missing server registration, or a bridge-side runtime error. It does not inherit from HungerLibError; it is a standalone exception rooted at Exception. 
from hungerlib.utils.exceptions import HungerBridgeError
Catch HungerBridgeError around any BridgeClient call to handle bridge communication failures gracefully: 
from hungerlib.utils.exceptions import HungerBridgeError

try:
    result = bridge.sendConsoleCommand("list")
except HungerBridgeError as e:
    print(f"HungerBridge returned an error: {e}")

​
Exception Hierarchy

Exception
├── ValidationError                  # base for all config validation errors
│   ├── FatalError                   # required fields missing or invalid
│   ├── TypeMismatchError            # type annotation mismatch
│   ├── FallbackError                # recommended field using fallback value
│   └── RecommendedError             # recommended key absent from YAML
│
├── HungerLibError                   # base for all HungerLib runtime errors
│   ├── InvalidLevelError            # bad log level passed to MessageRouter
│   └── InvalidModeError             # bad mode passed to getTPS / getPlayers
│
└── HungerBridgeError                # non-2xx response from HungerBridge

Build docs developers (and LLMs) love

Get started for freeTalk to us