Common errors and how to resolve them¶

literalizer raises a specific, typed exception whenever it cannot turn your data into valid code for the target language, rather than emitting source the compiler would reject. Every exception lives in literalizer.exceptions; this page groups them by the stage at which they are raised and renders each one’s meaning and the recommended fix directly from literalizer.exceptions, so the guidance here cannot drift from the API reference.

All exceptions are importable from literalizer.exceptions, so a name such as HeterogeneousScalarCollectionError below refers to literalizer.exceptions.HeterogeneousScalarCollectionError.

Parsing the input¶

Raised while reading source in the declared input_format, before any language-specific rendering.

exception literalizer.exceptions.ParseError

Raised when input cannot be parsed into a data structure.

Base class for every input-parsing failure; catch it to handle any malformed input uniformly. To resolve, validate the source against its declared input_format.

exception literalizer.exceptions.JSONParseError

Raised when a JSON string cannot be parsed.

To resolve, fix the JSON syntax, or pass the correct input_format if the data is really JSON5, YAML, or TOML.

exception literalizer.exceptions.JSON5ParseError

Raised when a JSON5 string cannot be parsed.

To resolve, fix the JSON5 syntax, or choose the matching input_format.

exception literalizer.exceptions.YAMLParseError

Raised when a YAML string cannot be parsed.

To resolve, fix the YAML syntax, or choose the matching input_format.

exception literalizer.exceptions.TOMLParseError

Raised when a TOML string cannot be parsed.

To resolve, fix the TOML syntax, or choose the matching input_format.

Mixed-type collections¶

Raised when the data mixes types within one collection but the target language requires that collection to be homogeneous. Each of these subclasses HeterogeneousCollectionError, so you can catch the base class to skip any input a strict-typed language cannot hold. The usual fix is to pick a non-default heterogeneous_strategy; see Heterogeneous strategies for the full discussion and JSON value types for the runtime JSON value alternative.

exception literalizer.exceptions.HeterogeneousCollectionError

Base class for errors raised when data is incompatible with the target language’s collection-shape constraints.

To resolve, pick a non-default heterogeneous_strategy (see Heterogeneous strategies) or render the value through a json_type (see JSON value types); catch this base class to skip any heterogeneous input a strict-typed language cannot hold.

exception literalizer.exceptions.HeterogeneousScalarCollectionError

Raised when a collection contains scalars of multiple types and the target language requires homogeneous scalar collections.

For example, [1, "two", 3.0] for a language that needs a single element type. To resolve, set heterogeneous_strategy to TAGGED_ENUM (or the language’s equivalent) to wrap each scalar, or to TUPLE for a fixed-length array.

exception literalizer.exceptions.HeterogeneousSiblingListsError

Raised when sibling sub-lists contain scalars that, combined, span multiple types and the target language requires homogeneous scalar collections.

To resolve, use a TAGGED_ENUM strategy, or render the value through a json_type.

exception literalizer.exceptions.MixedListValuesError

Raised when a list has elements spanning multiple type families and the target language requires homogeneous list elements.

To resolve, use a richer heterogeneous_strategy or a json_type.

exception literalizer.exceptions.MixedDictValuesError

Raised when a dict has values spanning multiple type families and the target language requires homogeneous dict values.

To resolve, use the RECORD strategy if the dict is conceptually a record, or a json_type for arbitrary mappings.

exception literalizer.exceptions.MixedDictKeysError

Raised when a dict has keys spanning multiple type families and the target language requires homogeneous dict keys.

To resolve, use a single key type, or render through a json_type.

exception literalizer.exceptions.MixedDictShapesError

Raised when a list contains dicts with different key sets and the target language requires uniform record shapes (e.g. Dhall).

To resolve, make every dict share the same keys, or use a json_type.

exception literalizer.exceptions.HeterogeneousSetError

Raised when a set contains scalars of multiple types and the target language requires homogeneous set elements.

To resolve, use one scalar type, or a richer heterogeneous_strategy.

exception literalizer.exceptions.TupleArityNotRepresentableError(*, arity: int)

Raised when the TUPLE heterogeneous strategy meets a tuple-eligible heterogeneous scalar array whose length the target language has no native fixed-size tuple for.

Kotlin only has Pair (two elements) and Triple (three elements); an array of any other length cannot be represented as a typed tuple without losing the per-position types, so literalize raises rather than falling back to a homogeneous list (which would re-trip the heterogeneity checks the strategy exists to satisfy). Subclasses HeterogeneousCollectionError so the same callers that already skip a heterogeneous input the language cannot represent also skip this one.

To resolve, shorten the array to a length the language supports, choose a language without the tuple-length cap (Rust, Scala), or switch to a TAGGED_ENUM strategy.

Values the target language cannot represent¶

Raised at the formatting boundary when an individual value has no faithful representation in the target language.

exception literalizer.exceptions.UnrepresentableInputError

Raised when an input value cannot be represented in the target language.

Used as the centralized error for shape-level rejections at the formatting boundary, e.g. when a dict carries a non-string key for a language whose surface syntax only admits string-typed keys. To resolve, adjust the data to a representable shape, or pick a language that supports it.

exception literalizer.exceptions.InvalidDictKeyError

Raised when a dict key cannot be represented in the target language.

This includes empty-string keys and keys containing characters that the language’s label syntax does not support (e.g. control characters in Dhall backtick-quoted labels). To resolve, remove or rename the offending key.

exception literalizer.exceptions.NullInCollectionError

Raised when a collection contains null elements and the chosen format does not support them (e.g. Java’s List.of()).

To resolve, remove the nulls, or select a collection format that admits them.

exception literalizer.exceptions.UnrepresentableIntegerError

Raised when an integer value exceeds the range the target language can represent natively.

Used by languages whose fixed-width integer types cannot hold values outside the signed 64-bit range (e.g. Fortran default integer, Cobol PIC S9(18), PureScript Int) when no external arbitrary-precision integer library is assumed to be available.

To resolve, keep integers within range, or target a language with wider or arbitrary-precision integers.

exception literalizer.exceptions.UnrepresentableEmptyDictError

Raised when an empty dict is passed to a target language whose runtime cannot distinguish an empty mapping from an empty sequence.

Lua, PHP, and R encode both empty arrays and empty objects with the same surface syntax ({}, [], and list() respectively), so the JSON encoders in their ecosystems serialize an empty mapping as []. The literalizer refuses to emit a literal that cannot round-trip rather than silently lose the mapping/sequence distinction.

To resolve, drop the empty mapping, or target a language that distinguishes the two.

exception literalizer.exceptions.UnrepresentableSpecialFloatError

Raised when a non-finite float (inf, -inf, or nan) is passed to a target language whose runtime cannot produce IEEE 754 special float values.

Used by Gleam on the Erlang target, which has no expression that evaluates to a non-finite float.

To resolve, replace the non-finite floats with finite values, or pick another language.

Identifiers and variable wrapping¶

Raised when variable_form or ref_case asks for output the target language cannot produce.

exception literalizer.exceptions.UnsupportedIdentifierCaseError(*, language_name: str, case_name: str)

Raised when literalize or literalize_call is passed a ref_case that is not in the target language’s supported_ref_cases – i.e. one that would not produce a syntactically legal identifier in the target language.

To resolve, choose a ref_case from the language’s supported_ref_cases.

exception literalizer.exceptions.VariableNameNotSupportedError(*, language_name: str, variable_name: str)

Raised when literalize is given a variable_form but the target language does not support variable-name wrapping.

To resolve, omit variable_form for that language, or target one that supports it.

exception literalizer.exceptions.WrapInFileWithoutVariableNotSupportedError(*, language_name: str)

Raised when literalize is called with wrap_in_file=True and variable_form=None for a target language that cannot represent a bare value at file-statement scope.

Most strict-typed compiled languages (Rust, C, C++, Haskell, Swift, OCaml, Ada, D, Dart, C#, Elm, Mojo, Nim, Objective-C, Odin, SML, V, Zig, etc.) require every top-level item to be a declaration; a bare expression at file scope is a syntax error. Such languages opt out of the shape by setting supports_no_variable_wrap_in_file to False, and literalize rejects the combination at the boundary instead of silently emitting invalid code.

To resolve, supply a variable_form so the value becomes a top-level declaration.

exception literalizer.exceptions.InvalidRecordNameError

Raised when record_struct_name_prefix or a value in record_shape_names is not a valid PascalCase identifier, collides with a reserved keyword of the target language, collides with heterogeneous_value_enum_name, or duplicates another mapped struct name.

To resolve, use distinct, valid PascalCase names that avoid reserved keywords.

Function calls¶

Raised by literalize_call() and its arguments (parameter_names, call_transform, zip_source, comment_source, target_function). See Rendering function calls.

exception literalizer.exceptions.CallsNotSupportedByLanguageError(*, language_name: str)

Raised when the target language itself has no function call syntax (e.g. pure data/markup formats like YAML, TOML, JSON5, Norg).

To resolve, use literalize() instead, or target a programming language.

exception literalizer.exceptions.CallsNotSupportedByToolError(*, language_name: str)

Raised when literalizer has not yet implemented function call rendering for the target language, even though the language itself has function call syntax.

To resolve, target a language whose call rendering is implemented.

exception literalizer.exceptions.PerElementNotListError

Raised when per_element=True but the parsed data is not a list.

To resolve, pass a list, or drop per_element.

exception literalizer.exceptions.ParameterCountMismatchError(*, expected: int, got: int)

Raised when the number of parameter_names does not match the number of argument values in a function-call row.

To resolve, make parameter_names the same length as each row of values.

exception literalizer.exceptions.CallArgNotSupportedError(*, language_name: str, reason: str)

Raised when a call argument value cannot be expressed as a positional argument in the target language’s call syntax.

Used by languages whose call syntax does not accept compound literals as arguments, e.g. Bash, where cmd (1 2 3) parses as a nested (...) child-process invocation rather than an inline array value.

To resolve, bind the value to a name first, or target a language that accepts the argument inline.

exception literalizer.exceptions.UnsupportedCallShapeError(*, language_name: str, reason: str)

Raised when literalize_call is given a call shape the target language cannot represent.

Distinct from CallArgNotSupportedError (which concerns individual argument values): this covers structural properties of the call itself, e.g. zero-parameter calls in languages whose syntax requires at least one operand.

To resolve, adjust the call shape, or target a language that supports it.

exception literalizer.exceptions.DottedCallTargetNotSupportedError(*, language_name: str, target_function: str)

Raised when literalize_call is given a dotted target_function but the target language does not support dotted call expressions.

To resolve, use a target name without dots, or target a language with dotted calls.

exception literalizer.exceptions.ZipSourceWithoutInputFormatError

Raised when literalize_call is given a zip_source but no zip_input_format describing how to parse it.

The companion source can only be parsed once its serialization format is known, so the two arguments must be supplied together.

To resolve, pass zip_input_format alongside zip_source.

exception literalizer.exceptions.ZipValuesWithoutCallTransformError

Raised when literalize_call is given a zip_source but no call_transform to consume the paired values.

The paired values are only reachable through zipped, so supplying them without a transform would silently discard them.

To resolve, supply a call_transform that reads zipped, or drop zip_source.

exception literalizer.exceptions.ZipValuesLengthMismatchError(*, call_count: int, zip_count: int)

Raised when literalize_call is given a zip_source whose parsed top-level elements differ in number from the generated calls.

To resolve, make zip_source hold one element per generated call.

exception literalizer.exceptions.CommentSourceLengthMismatchError(*, call_count: int, comment_count: int)

Raised when literalize_call is given a comment_source whose entry count differs from the number of generated calls.

Each comment is paired positionally with one call, so the two sequences must be the same length.

To resolve, provide one comment per generated call.

exception literalizer.exceptions.CommentSourceMultilineError(*, index: int)

Raised when a comment_source entry contains a newline.

A trailing comment is emitted on the statement’s last line; a newline would push the remainder onto a line with no comment leader and, in languages whose line comment runs to end of line, produce invalid source. Comments must be single-line.

To resolve, remove the newline, keeping each comment on one line.

Format option combinations¶

Raised when otherwise valid options combine into something the language cannot emit.

exception literalizer.exceptions.IncompatibleFormatsError

Raised when a combination of format options produces invalid code.

For example, Rust CONST and STATIC declaration styles require constant-expression initializers, but the VEC sequence format produces vec![…] which is not a constant expression.

To resolve, change one of the conflicting options so they agree.

exception literalizer.exceptions.WrapCombinedInFileNotSupportedError

Raised when a language does not support wrap_combined_in_file.

Languages that raise this error do not support BothVariableForms; literalize() rejects that form before reaching wrap_combined_in_file, but each language implementation still raises this typed exception as a safety net.

To resolve, use a single variable form, or target a language that supports the combined form.