libLogit

Error Taxonomy And Unsupported-Field Policy

This page defines how libLogit should fail when configuration, levels, paths, or optional features are wrong.

The goal is not to make every binding throw the exact same exception type. The goal is to make the failure shape predictable across bindings.

Why This Matters

Portable logging gets messy when one binding rejects a bad config clearly and another quietly accepts it. The user then thinks the SDK is portable when the real behavior is just drifting.

Beta needs a consistent answer to two questions:

what kinds of mistakes must fail fast?
what should a binding do with an optional field it does not really support?

High-Level Policy

libLogit should prefer:

fail fast for invalid config and invalid levels
fail clearly for contradictory path settings
reject unknown top-level config keys where the schema/parser can do so
avoid silent false support for optional or advanced fields

The SDK should avoid:

writing partial bad output after a configuration error
silently discarding a field the user reasonably expects to work
hiding unsupported behavior behind a successful parse

Error Categories

1. Configuration Shape Errors

These happen when the overall structure is wrong.

Examples already present in the repo:

LOGIT structure must be an object
Configuration root must be an object
defaults must be an object
logits must be a non-empty object
LOGIT '<name>' must be an object

Expected policy:

fail before any logging occurs
point at the bad structure, not just “invalid config”

2. Unknown Or Unsupported Key Errors

These happen when the config contains keys the binding/schema does not recognize.

Examples already present in the repo:

Unsupported configuration keys: [...]
Unsupported LOGIT configuration keys: [...]
Unsupported redaction options: [...]
Unsupported buffering options: [...]
Unsupported failurePolicy options: [...]

Expected policy:

reject unknown keys at schema or parser time where practical
list the offending keys directly
reserve no-op handling for explicitly documented compatibility cases only

3. Level Errors

These happen when the level is wrong by value or type.

Examples already present in the repo:

Unknown level: <value>
level must be a string, got <type>
level.threshold is required when level is an object

Expected policy:

invalid levels fail before writing
the error should name the bad level or bad type

4. Path And Path-Mode Errors

These happen when path semantics contradict each other.

Examples already present in the repo:

outputDirectory requires pathMode 'directory'
pathMode must be one of [directory, file]
<name> cannot be an empty string

Expected policy:

contradictory path config fails before file output
the error should name the exact conflicting field pair

5. Sink Vocabulary Errors

These happen when a sink name is not part of the binding’s supported contract.

Examples already present in the repo:

Unknown sink: <name>
sinks entries must be strings
sinks must be a list

Expected policy:

reject invalid sink names rather than silently dropping them
name the bad sink directly

6. Advanced-Feature Validation Errors

These happen when Python-reference advanced fields are malformed.

Examples already present in the repo:

redaction.patterns contains invalid regex: ...
buffering.mode must be one of [...]
failurePolicy.fallbackPath is required when mode is fallback
rotation.maxBytes is required when rotation.maxFiles is set
databasePath is required when the database sink is enabled

Expected policy:

if a binding implements the feature, it should validate it explicitly
if a binding does not implement the feature, it should reject it clearly or mark it as documented non-portable behavior

Unsupported-Field Rules

For optional or advanced fields, a binding should do exactly one of these:

implement the field and test it
reject the field clearly during parse/setup
document the field as a no-op with explicit limits

What a binding should not do:

accept the field quietly
ignore it quietly
leave the user believing portable behavior exists when it does not

Current Repo Reality

Portable baseline fields

These are strong enough to teach broadly today:

localPath
outputDirectory
pathMode
remotePath
level
format
metadata
sinks
rotation
retention

Python-first advanced fields

These have the strongest direct validation and runtime proof in Python:

redaction
buffering
failurePolicy
databasePath plus richer retention behavior

Other bindings should currently be treated as baseline implementations unless their docs and tests say otherwise.

Recommended Error Style

Across bindings, the wording does not need to be byte-for-byte identical. But good libLogit errors should usually have these qualities:

name the bad field
name the bad value or type
describe the expected value family
fail before corrupted or misleading output is written

Good examples from the current repo:

Unknown level: panic
outputDirectory requires pathMode 'directory'
buffering.capacity must be a positive integer
failurePolicy.fallbackPath is required when mode is fallback

Relationship To Conformance

Not every exact error string needs cross-binding conformance today. But the failure category should remain stable:

invalid levels fail
bad path-mode combinations fail
unknown sinks fail
unsupported advanced features are not silently claimed

That is enough to make the SDK feel coherent while Beta hardens the full binding matrix.

Where To Look For Evidence