Error Category Details

This section provides a deeper look into the predefined error categories of the Erbsland Configuration Language (ELCL). Each category groups together similar types of parsing issues, making it easier to understand, classify, and respond to errors in a structured and meaningful way.

Relaxed Handling of Specialized Syntax Errors

Some error types in the Erbsland Configuration Language (ELCL) are easy to classify—for example, issues related to IO, Encoding, or NameConflict are clearly defined and straightforward to detect. However, other categories such as Character, UnexpectedEnd, Indentation, LimitExceeded, and Unsupported are significantly harder to implement with precise reporting. These are specialized subtypes of general Syntax errors.

To simplify implementation, any parser that conforms to the ELCL specification is allowed to report such cases using the generic Syntax error code, even if a more specific category would technically be more accurate.

This means that while specialized categories are available for better diagnostics, parser implementations are not required to distinguish them. This show allow smaller implementations—especially useful for micro-parsers or resource-constrained environments.

Distinct Error Categories	Specialized Syntax Categories
IO Encoding NameConflict Signature Access Validation Internal	Syntax ▲ UnexpectedEnd Character LimitExceeded Indentation Unsupported

Note

The ▲ symbol indicates that all specialized syntax categories conceptually derive from Syntax. Parsers may always choose to report these cases using the more general Syntax code without violating the specification.

Error IO

The IO category covers all errors related to input/output operations, typically originating from the underlying operating system or file system.

These errors are considered external to the document’s syntax and structure and should be reported as early as possible. Since they are not tied to a specific part of the parsed content, it’s more important to return them immediately rather than attempt precise location tracking.

The error message should include:

• A short identifier to indicate the affected source (e.g., filename or stream name).

• The exact error returned by the OS or runtime.

Error Encoding

The Encoding category is used exclusively for UTF-8 decoding errors. It only applies to:

• Invalid UTF-8 byte sequences.

• Valid UTF-8 sequences that represent disallowed Unicode code points (such as surrogate pairs or out-of-range characters).

It does not apply to legal characters that are disallowed by ELCL’s rules—that is covered by the Character category.

Refer to Characters for full details on encoding rules and a list of illegal UTF-8 sequences that must be rejected.

When reporting an encoding error:

• Always treat it as a high-priority issue.

• Do not mask it with later-stage Syntax errors.

• Ensure that valid text preceding the error is still processed correctly.

Error UnexpectedEnd

The UnexpectedEnd category is a specialized subtype of the general Syntax error. It is reserved for cases where the document ends prematurely, leaving a construct incomplete. This error can only occur at the very end of the document. If an invalid or partial construct appears earlier in the file, it must be reported as a Syntax error instead.

Typical examples of UnexpectedEnd include:

• An unterminated text block.

• A value name followed by a separator but no value.

• A carriage return at the end of the document with no following line-feed.

Design Rationale

The purpose of the UnexpectedEnd category is to help applications detect situations where the document may not have been fully read—for example, when data is received from an unreliable source such as a network stream or incomplete file transfer. A parser returning this error allows the application to retry or request retransmission.

While the line-based structure of ELCL makes it difficult to perfectly distinguish between syntax errors and premature ends, this category serves as a useful signal in practical scenarios. It can reveal edge cases that general Syntax errors would otherwise obscure.

Error Character

The Character error category is a specialized subtype of the general Syntax error. It is triggered when a character is valid UTF-8, but explicitly disallowed by the ELCL specification.

This error is not an encoding issue—UTF-8 decoding has already succeeded. Instead, Character errors arise when a disallowed Unicode code point appears in the document. Common examples include:

• Control characters such as U+0000.

• Other restricted Unicode ranges as defined in Characters.

Note

This category does not apply to valid characters that are disallowed only in certain syntactic contexts. For example, if a + character appears in a regular name (which is structurally invalid), the error should be reported as Syntax, not Character.

For a complete list of prohibited characters and ranges, see Characters.

Design Rationale

The Character category serves a similar purpose to Encoding: it helps detect malformed or corrupted documents early in the parsing process. While technically well-formed in terms of encoding, documents containing forbidden characters are considered invalid by ELCL rules.

By distinguishing encoding-level issues from specification-level character constraints, parser implementations can produce clearer diagnostics. This separation also enables applications to handle user errors differently from technical decoding failures.

Error Syntax

The Syntax category is the default for any violation of the ELCL grammar or structure, when no more specific category applies.

It serves as a general-purpose error type for malformed constructs, missing separators, misaligned indentation, unmatched quotes, and similar issues.

Use Syntax if:

• The document fails to follow the expected grammar.

• No other category—such as UnexpectedEnd, Character, LimitExceeded or Indentation—clearly matches the problem.

This category ensures that all structurally invalid configurations are properly reported, even if they don’t fit neatly into other predefined categories.

Error LimitExceeded

The LimitExceeded error category is a specialized subtype of the general Syntax error. It is used when a configuration document exceeds a defined numeric or structural boundary, such as size or depth limits.

Typical causes for this error include:

• A line exceeds the maximum allowed length of 4000 bytes.

• A regular name exceeds the maximum length of 100 characters.

• A name path contains more than 10 elements.

• A text, code block, regular expression, or binary data value exceeds the parser’s configured size limit.

• A byte-data format identifier exceeds the allowed length.

• The nesting depth of included documents exceeds five levels.

Note

While these limits are enforced by all full-featured parsers, micro-parsers may impose stricter constraints. Refer to the relevant chapters for the exact limits applied by your target parser.

Error NameConflict

The NameConflict error category is used when a name is reused or conflicts with a previously defined value or section.

In ELCL, each name must be unique within its scope. This includes:

• Defining the same section or value name more than once.

• Defining a section and a value with the same name path.

• Mixing regular names and text names within the same section.

All possible causes and edge cases for name conflicts are described in detail in Name Conflicts.

Error Indentation

The Indentation error category is a specialized subtype of the general Syntax error. It is raised when spacing or indentation does not match the expected pattern.

This applies specifically to:

• Multiline values with inconsistent indentation.

• List entries or text blocks that are not properly indented.

• Any content that violates the required spacing before continuation lines.

This category does not apply if a value list or block ends unexpectedly or is malformed—such cases fall under Syntax.

For a complete overview of indentation rules, see Spacing.

Error Unsupported

The Unsupported error category is a specialized subtype of the general Syntax error. It indicates that the document uses a feature not supported by the parser.

There are three primary cases where this error can occur:

• The document declares a @version meta value, with a language version that is not supported by the parser.

• The document declares its required features using the @features meta value, and one or more are not supported.

• The parser encounters a construct or value type it does not support, even if the @features meta value is not present.

In parsers that do not implement feature tracking, unsupported features may also be reported as Syntax errors instead. However, when feature-awareness is enabled, Unsupported should be used to clearly distinguish between unsupported constructs and general syntax errors.

See also: Feature Identifiers

Error Access

The Access error category is used when access to a document source is explicitly denied by user code or a custom access policy.

This commonly applies to documents referenced via the @include meta command. For example, a callback may be used to restrict access to certain files, directories, or external sources.

See Meta Command “Include” for details on how the @include mechanism works and how access control can be implemented.

Error Validation

The Validation error category is used when a document fails to meet semantic validation rules—beyond syntax and structure.

This includes:

• Invalid values according to schema rules.

• Missing required keys or sections.

• Constraint violations such as disallowed combinations.

Refer to Validation Rules for an overview of how validation rules can be defined and evaluated.

Error Signature

The Signature error category is used when a document contains a digital signature that is either invalid or cannot be verified.

This error may be triggered in the following situations:

• The signature does not match the document contents.

• The verification key or algorithm is unsupported or missing.

• The signature format is malformed.

See Meta Command “Signature” for implementation guidelines on how digital signatures can be added to documents and verified during parsing.

Error Internal

The Internal error category is reserved for fatal errors that originate within the parser itself—typically due to unexpected conditions, logic bugs, or implementation faults.

Such errors indicate that the parser has entered an invalid or unrecoverable state. While rare, they serve as a safeguard for parser integrations, allowing the host application to detect and handle critical failures gracefully.

This error should be reserved for true internal inconsistencies or unexpected exceptions—not for user mistakes or invalid input.

Note

Use of the Internal error category is optional. If the implementation language provides a more appropriate mechanism—such as exceptions or assertions—for reporting unexpected internal conditions, that approach may be preferred. The Internal error is available when no better alternative exists or as a deliberate design choice within the parser interface.