Table of Contents

Errors across the line formats

Each line format - Delimited, DotEnv, and INI - reports failure through exactly two exception types, and the split is the same in all three: a format exception for input that is not well-formed, and a serialization exception for a well-formed document that does not bind to the target type. This guide shows what each type carries, which inputs trigger it, how to catch it, and which reader-option policies turn a would-be error into tolerated input.

The two families

Format exception Serialization exception
Delimited DelimitedFormatException - LineNumber, Offset DelimitedSerializationException
DotEnv DotEnvFormatException - LineNumber, ColumnNumber, Offset DotEnvSerializationException
INI IniFormatException - LineNumber, Offset IniSerializationException
Base type FormatException Exception
Raised by the readers, both DOMs, and the serializer's read path the serializer's bind (read) and shape checks (write)
Position members 1-based LineNumber, 0-based byte Offset (DotEnv adds a 1-based ColumnNumber, counted in bytes); all int? - null when the failure has no single position none; the message names the key or column
InnerException rarely set the FormatException from a failed scalar conversion, when there is one

Two points follow from the table. First, the position members are nullable: a structural rule that spans the whole document - an INI global key colliding with a section of the same name, as IniDocument checks it, for example - reports no line. Second, the serializer's read path can throw either type: the document is parsed first (format exception), then bound (serialization exception), so a catch that must handle both needs two clauses.

Pattern 1 - Delimited: malformed input

The Delimited reader enforces RFC 4180 structure. An unterminated quoted field, a record whose field count disagrees with the header, characters after a closing quote, and a duplicate header name are all DelimitedFormatException:

using Bodu.Text.Delimited;
using Bodu.Text.Delimited.Document;

try
{
    using DelimitedDocument doc = DelimitedDocument.Parse("symbol,qty\nMSFT,\"10\n"u8);
}
catch (DelimitedFormatException ex)
{
    Console.WriteLine($"{ex.Message} (line {ex.LineNumber}, offset {ex.Offset})");
}
// A quoted delimited field was not terminated before the end of the input. (line 3, offset 20)

The other structural failures, with the position each reports:

Input Message Position
symbol,qty / MSFT,10,extra A delimited record has 3 field(s) but the header declares 2. line 2, offset 11
symbol,qty / MSFT,"10"x A quoted delimited field is followed by text other than a delimiter, a line break or the end of the input. line 2, offset 20
symbol,symbol / MSFT,10 The delimited header row contains the duplicate column name 'symbol'. line 1, offset 0

An error about a whole record - a field count that disagrees with the header, or a header that repeats a name - is reported where that record starts: the line it begins on and the offset of its first byte. Text after a closing quote is reported at the first offending byte, and an unterminated quoted field where the reader detected it, at the end of the input.

Pattern 2 - Delimited: tolerating dirty input

Three DelimitedReaderOptions policies convert the errors above into accepted input. Each has a strict default; the leniency is opt-in:

Policy Default Lenient value Effect
FieldCountBehavior Strict Ragged Records with more or fewer fields than the header are accepted as-is.
MalformedRecordBehavior Throw SkipRecord A malformed record - one with text after a closing quote, or one whose field count breaks Strict - is skipped whole, and reading continues with the next line.
DuplicateHeaderBehavior Throw TakeFirst / TakeLast A repeated column name maps to the first or last occurrence; the other columns with the name are read under an empty name.
using Bodu.Text.Delimited.Reader;

using DelimitedDocument ragged = DelimitedDocument.Parse(
    "symbol,qty\nMSFT,10,extra\nAAPL\n"u8,
    new DelimitedReaderOptions { FieldCountBehavior = DelimitedFieldCountBehavior.Ragged });
int raggedCount = ragged.RootElement.GetArrayLength();    // 2 records

using DelimitedDocument skipped = DelimitedDocument.Parse(
    "symbol,qty\nMSFT,\"10\"x\nAAPL,5\n"u8,
    new DelimitedReaderOptions { MalformedRecordBehavior = DelimitedMalformedRecordBehavior.SkipRecord });
int skippedCount = skipped.RootElement.GetArrayLength();  // 1 record - the malformed MSFT record is skipped whole

using DelimitedDocument last = DelimitedDocument.Parse(
    "symbol,symbol\nMSFT,10\n"u8,
    new DelimitedReaderOptions { DuplicateHeaderBehavior = DelimitedDuplicateHeaderBehavior.TakeLast });
string symbol = last.RootElement[0].GetProperty("symbol").GetString();   // "10"

An unterminated quoted field is never tolerated - there is no policy for it, because the reader cannot know where the record was meant to end. The full dialect table is on the parser policies page. Note that these policies live on the reader options, which the DOMs and the token reader accept; DelimitedSerializerOptions exposes only the dialect characters (Delimiter, Quote, CommentChar) and NoHeader, so a typed DelimitedSerializer.Deserialize<T> always reads strictly.

Pattern 3 - Delimited: binding failures

A well-formed document that does not fit the record type raises DelimitedSerializationException. The typical cause is a scalar that does not parse; the FormatException from the conversion is preserved as the inner exception:

public sealed class Trade
{
    public string Symbol { get; set; } = "";
    public int Quantity { get; set; }
}
try
{
    DelimitedSerializer.Deserialize<Trade>("Symbol,Quantity\nMSFT,ten\n");
}
catch (DelimitedSerializationException ex)
{
    Console.WriteLine(ex.Message);
    Console.WriteLine(ex.InnerException?.Message);
}
// The delimited value for column 'Quantity' could not be converted to type 'System.Int32'.
// The input string 'ten' was not in a correct format.

The record type is checked before anything is read or written. A record is a string[] or an object whose members map to columns, so since 1.3.0 a scalar or collection record type throws A delimited record is a string array or an object whose members map to columns; the record type '...', a scalar or a collection, is not supported., and reading into an abstract record type, or one with no public parameterless constructor, throws The record type '...' cannot be created; reading a delimited record needs a public parameterless constructor. Since 1.3.0 the check also covers the record type's members, each of which is one field: a member whose type is not a scalar, such as a dictionary or a class, throws The delimited column '...' has the type '...', which is not a scalar, so no field maps to it. before anything is read or written, from every Serialize, Deserialize and DeserializeAsyncEnumerableAsync overload alike, and writing throws it for a member declared as object when the value it holds is not a scalar. Earlier versions wrote the value's ToString() text, which did not read back, and read such a type whenever the document had no column for the member.

A missing column is not an error - Delimited does not honor [Required], so Symbol\nMSFT\n binds a Trade with Quantity left at its default. And because the document is parsed before it is bound, a structural error inside the same call still surfaces as the format exception:

DelimitedSerializer.Deserialize<Trade>("Symbol,Quantity\nMSFT,\"1\n");
// → throws DelimitedFormatException: A quoted delimited field was not terminated before the end of the input.

Pattern 4 - DotEnv: malformed input

The DotEnv reader reports a line, a column, and a byte offset on every structural failure. All three describe one position, the byte at which it found the error or the opening quote of an unterminated value, and the column counts bytes from the start of the line:

using Bodu.Text.DotEnv;
using Bodu.Text.DotEnv.Document;

try
{
    using DotEnvDocument doc = DotEnvDocument.Parse("API_KEY=\"abc\n");
}
catch (DotEnvFormatException ex)
{
    Console.WriteLine($"{ex.Message} (line {ex.LineNumber}, column {ex.ColumnNumber}, offset {ex.Offset})");
}
// Unterminated double-quoted DotEnv value beginning on line 1. (line 1, column 9, offset 8)
Input Message Position
=abc Invalid DotEnv key name '=' on line 1; keys must match [A-Za-z_][A-Za-z0-9_]*. line 1, column 1, offset 0
API KEY=abc Malformed DotEnv entry on line 1; expected 'KEY=VALUE'. line 1, column 5, offset 4
export API_KEY=abc with DisallowExportPrefix = true Malformed DotEnv entry on line 1; expected 'KEY=VALUE'. line 1, column 8, offset 7
API_KEY="abc"def Unexpected text after the closing quote of a DotEnv value on line 1. line 1, column 14, offset 13

The DotEnv knobs on DotEnvReaderOptions run in the strict direction - the default dialect is already the permissive mainstream dotenv reading, and each option removes a feature: DisallowExportPrefix makes an export line malformed (above), DisallowInlineComments stops # note from terminating an unquoted value (so KEY=abc # note reads as abc # note instead of abc), and SkipComments drops comment lines from the token stream. None of them turns an error into accepted input.

Pattern 5 - DotEnv: binding failures

DotEnvSerializationException covers the binding failures: a [Required] key that is absent (a member declared with the C# required keyword counts as [Required]), a value that does not convert, and a type that cannot hold the document:

public sealed class ApiSettings
{
    [Required]
    public string ApiKey { get; set; } = "";

    public int Timeout { get; set; } = 30;
}
DotEnvSerializer.Deserialize<ApiSettings>("TIMEOUT=10\n");
// → throws DotEnvSerializationException: Required DotEnv key 'ApiKey' was not present in the document.

DotEnvSerializer.Deserialize<ApiSettings>("ApiKey=k\nTimeout=soon\n");
// → throws DotEnvSerializationException: The DotEnv value for key 'Timeout' could not be converted to type 'System.Int32'.
//   InnerException: FormatException: The input string 'soon' was not in a correct format.

The type is checked as well. A DotEnv root is an object or a string-keyed dictionary (any type that implements IDictionary<string, TValue>, whether or not it also implements the non-generic IDictionary), so a scalar root (a primitive, string, an enum, decimal, Guid, a date or time type, Uri, a 128-bit or half-precision number, BigInteger, or the nullable form of one) or a collection root throws DotEnv serialization requires an object or string-keyed dictionary root; the type '...' is not supported., from Serialize and Deserialize alike. Since 1.3.0 a dictionary that implements only the generic interface is written and read through it, in DotEnv and INI alike, where earlier versions rejected it as a root on write and threw InvalidCastException on read. A dictionary whose type is not keyed by string, such as Hashtable, SortedList or Dictionary<int, string>, is a collection, so since 1.3.0 it throws the same root-type exception, in DotEnv and INI alike, where earlier versions wrote its entries and read it back as an empty instance. Since 1.3.0 the check also covers every scalar: earlier versions bound decimal, Guid, the date and time types, Uri, the 128-bit and half-precision numbers, BigInteger and the nullable forms as objects, through their public properties. Since 1.3.0 a type with a member whose type is not a scalar, such as a nested dictionary or a class, throws The DotEnv key '...' has the type '...', which is not a scalar, so no DotEnv value maps to it. from Serialize and Deserialize alike, before anything is written or read, whatever the member holds and whatever the ignore condition, and Serialize throws it for a dictionary entry of such a type, or a member declared as object holding such a value, when it writes one. Earlier versions wrote the value's ToString() text, which did not read back, and read such a type whenever the document had no key for the member. Reading into an abstract type, or one with no public parameterless constructor such as a positional record, throws The type '...' cannot be created; reading a DotEnv document into it needs a public parameterless constructor. rather than the runtime's MissingMethodException. A type that maps two members to one key, through [PropertyName] or the naming policy, throws The type '...' maps more than one member to the DotEnv key '...'. from Serialize and Deserialize alike, before anything is read or written; INI and Delimited reject such a type the same way.

As with Delimited, a syntax error in the same call is the format exception (ApiKey="k → Unterminated double-quoted DotEnv value beginning on line 1.), so handlers around Deserialize<T> need both clauses.

Pattern 6 - INI: malformed input and document-model rules

The INI reader's dialect is deliberately conservative: = is the only delimiter, a header must close on its line with nothing but whitespace or a comment after it, and any other comment is a line of its own. Those produce positioned IniFormatExceptions:

using Bodu.Text.Ini;
using Bodu.Text.Ini.Document;

try
{
    using IniDocument doc = IniDocument.Parse("[server]\nport: 8080\n");
}
catch (IniFormatException ex)
{
    Console.WriteLine($"{ex.Message} (line {ex.LineNumber}, offset {ex.Offset})");
}
// Malformed INI entry on line 2; expected 'key=value'. (line 2, offset 19)
Input Message Position
[server / port=8080 An INI section header was not terminated with ']' before the end of the line. line 1, offset 7
[server] port / port=8080 Unexpected text follows the INI section header on line 1; only whitespace or a comment may follow the closing ']'. line 1, offset 9
# c / k=1 with DisallowHashComments = true Malformed INI entry on line 1; expected 'key=value'. line 1, offset 3
server=1 / [server] / port=8080 The global INI key 'server' collides with a section of the same name. no position (null)

INI has a second source of format exceptions: the document-model duplicate policies in IniDocumentOptions. The source-order reader reports the file verbatim; it is the normalized document (and therefore both DOMs and the serializer) that decides what a repeated key or section means. The defaults are lenient (Merge sections, LastWins keys) and the strict values raise the format exception:

using Bodu.Text.Ini.Reader;

IniDocument.Parse("[s]\nk=1\nk=2\n"u8, IniReaderOptions.Default,
    new IniDocumentOptions { DuplicateKeyBehavior = IniDuplicateKeyBehavior.Disallowed });
// → throws IniFormatException: The INI section 's' defines the key 'k' more than once. (line 3, offset 8)

IniDocument.Parse("[s]\nk=1\n[s]\nj=2\n"u8, IniReaderOptions.Default,
    new IniDocumentOptions { DuplicateSectionBehavior = IniDuplicateSectionBehavior.Disallowed });
// → throws IniFormatException: The INI document defines the section 's' more than once. (line 3, offset 8)

IniSerializerOptions surfaces the same two policies, and its Strict preset (IniSerializerDefaults.Strict) sets both to Disallowed - the configparser strict mode. The global/section name collision is the one duplicate that no policy tolerates, because both entries would claim the same root property; IniSerializerOptions.GlobalSectionName sidesteps it by mapping the global entries to a reserved root key instead of hoisting them.

Pattern 7 - INI: binding failures

IniSerializationException adds a third cause to the two the other formats share - the format's depth limit. INI is two levels deep (section, then key), so a member that would need a third level is rejected, on write as well as on read:

public sealed class AppConfig
{
    [Required]
    public string Name { get; set; } = "";

    public Server Server { get; set; } = new();
}

public sealed class Server
{
    public int Port { get; set; } = 80;
}
IniSerializer.Deserialize<AppConfig>("[Server]\nPort=8080\n");
// → throws IniSerializationException: The INI document does not contain the required key 'Name'.

IniSerializer.Deserialize<AppConfig>("Name=x\n[Server]\nPort=eighty\n");
// → throws IniSerializationException: The INI value for key 'Port' could not be converted to type 'System.Int32'.
//   InnerException: FormatException: The input string 'eighty' was not in a correct format.

A Server type that itself held an object-typed member - public Tls? Tls { get; set; } - fails at first use with INI supports only two levels (section then key); the member 'Tls' nests deeper., whether or not the member is null: the check is on the type's shape, not the instance. A root member declared as object, which could be a key or a section, throws The INI member '...' is declared as object, which maps to neither a key nor a section. in the same way. Since 1.3.0 the root type, with the declared type of every section it names, is checked whole, once per type and options instance, before the input is read or anything is written: every mapped member is checked, whether it can be read, set or both, and every section type whether or not the instance holds a section, so a type is rejected in both directions or in neither, and reading rejects it even when the document has no such section. Earlier versions checked a member only where they reached it, after skipping the members they could not read or set and the sections that were null, so some such types wrote a document that did not read back, or read a document into a value they then refused to write, and an object member was written as a section and read back as a bare object, dropping its keys. A member left out with [Ignore] is not checked.

The root type is checked as it is for DotEnv: an INI root is an object or a string-keyed dictionary, so a scalar or collection root throws INI serialization requires an object root; the type '...' is not supported. on write and on read. A dictionary whose type is not keyed by string is a collection there too, and as a section member, the global-section member or a root dictionary's entry it throws the depth message above, naming the member or entry, where earlier versions wrote it as a section and read a section member or the global-section member back as an empty dictionary. Since 1.3.0 a dictionary entry that is not a section, at the root or in a section, throws The INI section '...' has a value for the key '...' of type '...', which is not a scalar and cannot be written so that it reads back. when its value is not null or a scalar, such as a List<T>, where earlier versions wrote the value's ToString() text. Under IgnoreCondition.Never a null entry of a dictionary root is decided by the dictionary's value type: since 1.3.0 a section type writes an empty section, where earlier versions wrote an empty global key that did not read back, and a value type that is neither a scalar, object nor a section type throws the same message, naming that type. Since 1.3.0 that includes DateOnly, TimeOnly, the 128-bit and half-precision numbers and BigInteger, and their nullable forms, which earlier versions bound as objects through their public properties. A null entry of a dictionary written as a section is decided by that dictionary's value type in the same way, except that a string-keyed dictionary type, a third level, throws the depth message; earlier versions wrote every such entry as an empty key. Reading into an abstract type, or one with no public parameterless constructor, whether the root or the type of a section, throws The type '...' cannot be created; reading an INI document into it needs a public parameterless constructor. rather than the runtime's MissingMethodException.

Pattern 8 - Catch both families

Because the serializer's read path parses and then binds, a robust handler distinguishes the two and uses the position when there is one:

public static AppConfig? TryLoad(string ini, Action<string> report)
{
    try
    {
        return IniSerializer.Deserialize<AppConfig>(ini);
    }
    catch (IniFormatException ex) when (ex.LineNumber is int line)
    {
        report($"line {line}: {ex.Message}");
    }
    catch (IniFormatException ex)
    {
        report(ex.Message);
    }
    catch (IniSerializationException ex)
    {
        report(ex.InnerException is null ? ex.Message : $"{ex.Message} ({ex.InnerException.Message})");
    }

    return null;
}

The format exceptions derive from FormatException, so a single catch (FormatException) covers all three formats' syntax errors where the format is not known in advance; the serialization exceptions derive directly from Exception and have no common base, by design - a caller binding a known format catches the specific type.

Where to go next