Pre-checking TOML configurations with Python's tomllib: Preventing type mismatch issues despite valid syntax

About this article
This article was created using an automated generation workflow leveraging generative AI. We verified the official Python specifications fortomlliband created a sample to inspect a fictitious TOML configuration file in read-only mode. We executed 19 unit tests, syntax checks, CLI normal paths, and file-not-found error paths on Python 3.13.5 in an isolated Linux container.

Verification status: 🧪 Locally executed and 19 tests passed on Linux / Python 3.13.5. Windows/macOS unverified. Codex CLI and GitHub Actions not run.

Supported Environments, Capabilities, and Limitations

Try first

Daily Code completed version and READMEare used to test with dummy settings only. Live browser interaction with public links is not performed this time.

1. demo.tomlandcheck_toml.pyare placed in the same folder.

2. Run on Python 3.11 or laterpython3 check_toml.py demo.tomland verifySTATUS=VALIDand exit code0(on Windows, refer to the followingpy -3）。

3. Copy the source file, renameretries = 2toretries = "2"and re-run. The expected result isINVALID_RETRIESand exit code2。

Note:The operations shown here are a test design for existing samples. A distinction is made between past actual measurements of 19 passed isolated Linux tests on October 29, 2026, and the fact that new physical device testing has not been performed this time.

"The configuration file was read successfully, but starting the application failed." In such troubleshooting scenarios, a shortcut is to investigate separately whetherthe configuration file syntax is correctandthe configuration values match what the application expectsThis time, the Python standard librarytomllibWe will build a small CLI that uses this to sequentially validate syntax, required fields, and types without altering the configuration.

The following example is used by a fictional applicationdemo.toml. No actual API keys, internal URLs, or passwords are used.

[app]
name = "demo"
enabled = true
retries = 2

Even if the syntax is correct, configuration value types must be checked separately.

tomllibconverts TOML 1.0.0 contents into Python dictionaries or similar structures.enabled = trueIn Python, this corresponds tobool、retries = 2and in others, it isint. However, even if you writeretries = "2"it is still valid TOML syntax. Because quotes were addedthe type of the value changes to a string, making it unsuitable for applications that require an integer.

Therefore, we split the validation into two stages: the first stage checks whether it can be parsed as TOML, and the second stage verifies that[app]thenameis a non-empty string, thatenabledis a boolean, and thatretriesis an integer between 0 and 10. The range 0 to 10 is a custom rule for this tutorial and not a limitation of the TOML specification.

The official Python documentation"tomllib — Parsing TOML files"notes thattomllibwas added in Python 3.11, is read-only and does not support writing, and raises an error on syntax violationsTOMLDecodeErrorIt explains how to output . This time, we will leverage this property and will not perform automatic configuration fixes or application launches.

Try it on your own PC

The complete version is available inDaily Code Samples: Pre-inspection of TOML Configuration.README.md、check_toml.py、test_check_toml.py、demo.tomlPlace the four files in the same folder. For Windows, usepy -3, and for Linux/macOS, usepython3; replace these with a command that can launch Python 3.11 or later.

Trying the same tutorial on Windows PowerShell (untested)

On Windows, open PowerShell and navigate to the folder where the four sample files are located. First, usepy -3 --versionto verify whether Python is3.11 or later.py -3In environments wheretomllibselects version 3.10 or earlier, you cannot usepy -0p. If multiple Python installations exist, check the candidates using and explicitly specify an environment with version 3.11 or later before proceeding.

py -3 --version
py -3 .\check_toml.py .\demo.toml
$LASTEXITCODE

The expected output is the same as the successful Linux exampleSTATUS=VALID CHECKS=APP_NAME_ENABLED_RETRIES. However, execution on Windows has not been verified. In PowerShell,$LASTEXITCODEYou can check the exit code with. If the command is not found, verify the presence of the Python Launcher and the PATH variable; do not rush to obtain administrator privileges or run unknown installers.

Create the comparison file without overwriting the original.

Copy-Item -LiteralPath .\demo.toml -Destination .\demo-copy.toml
notepad .\demo-copy.toml

In Notepad,retries = 2onlyretries = "2"to, and after saving, run the following.

py -3 .\check_toml.py .\demo-copy.toml
$LASTEXITCODE

The expected result isSTATUS=INVALID ISSUE=INVALID_RETRIESand exit code2. The normal operation returns an exit code of0, and when the file cannot be read, it is3. The Windows operations shown here have not been empirically measured, so readers should verify the actual values in their own environments. File editing and launching Notepad arelocal operations performed by the readerand were not executed during the creation of this manuscript.

First execution: Reading a valid configuration

Navigate to the sample folder in the terminal and run the following.

python3 check_toml.py demo.toml

The output actually verified on Linux / Python 3.13.5is the following single line. The exit code was0.

STATUS=VALID CHECKS=APP_NAME_ENABLED_RETRIES

This message indicates that the syntax and type checks have passed for the three items in the training material. The configuration values themselves are not printed to the screen. Additionally,STATUS=VALIDisnot an indication that guarantees successful application startup or the safety of the configuration contents.Unknown keys are allowed in this tutorial, and their semantics are not validated.

Mechanism: Check for required fields after reading

A brief summary of the core of the completed version is based on the following concept. This is an explanatory excerpt; handling for file sizes, I/O exceptions, and exit codes can be found in the completed version on GitHub.

import tomllib

with open("demo.toml", "rb") as f:
    data = tomllib.load(f)

app = data.get("app")
if not isinstance(app, dict):
    raise ValueError("[app]がありません")
if type(app.get("enabled")) is not bool:
    raise ValueError("enabledの型が違います")
if type(app.get("retries")) is not int:
    raise ValueError("retriesの型が違います")

tomllib.load()isa file opened in binary mode. The completed version reads up to 64 KiB, decodes it as UTF-8, and passes it totomllib.loads(). Official documentation warns that parsing untrusted TOML without limits can consume significant CPU and memory resources. Size limits are one countermeasure, but they do not provide complete protection against all malicious inputs.

type(value) is intis used because in Pythonboolisinta subclass ofisinstance(True, int)evaluates to true.retries = trueTo prevent accidentally accepting as an integer, the types are compared strictly here.

Make one change: Convert the number to a string

Leave the includeddemo.tomlas is, createan alias copy, and changeretries = 2toretries = "2". While both are valid TOML, the latter is not an integer.

[app]
name = "demo"
enabled = true
retries = "2"

the copied file todemo-copy.tomlHere is an execution example when saved as.

python3 check_toml.py demo-copy.toml

Expected outputis as follows. Although the CLI execution for this specific procedure has not been performed, unit tests have confirmed failure for string types.

STATUS=INVALID ISSUE=INVALID_RETRIES

The exit code is2designed to be. In actual operations, automatically converting the original string to an integer can sometimes mask input errors. Here, the approach is to stop at the stage where the "incorrect type" is detected and have the configuration owner fix it.

Categorizing failures into three layers

In this way,Invalid TOML syntax、Invalid types or missing required fields for the application、Issues where files cannot be readSeparating these makes the investigation sequence clear. Exit codes are valid0content mismatch2and I/O failure3. Additionally, incorrect command argument specifications also result inargparsestandard processing being2.

What was verified through 19 tests

The following was executed in an isolated Linux container using Python 3.13.5.

python3 -m unittest discover -p 'test_*.py' -v
python3 -m py_compile check_toml.py test_check_toml.py
python3 check_toml.py demo.toml

All 19 tests passed, syntax checks passed, and the normal CLI completed with exit code 0. When passing a non-existent file, it resulted inSTATUS=IO_ERROR ISSUE=NOT_REGULAR_FILEwith an exit code of 3. Unit tests have verified duplicate keys, invalid UTF-8, empty strings, mixing booleans and integers, size limits, symbolic links, and ensuring placeholder values are not displayed on errors. Codex CLI was not found in this execution environment, so implementation and verification using Codex were not performed. GitHub Actions were also not executed due to billing limits.

Precautions for production use

Applying this sample directly to actualpyproject.tomlor application configurations will fail because[app]the tutorial table does not exist. Rather than using it as a general-purpose TOML validator,use it as an example defining settings required by your own application. If the target is[database], you must separately design the required keys and types to match your application specifications.

Furthermore, configurations may contain sensitive information. The sample does not output values, but do not commit actual files to public repositories or paste the entire configuration into an AI. File paths may also remain in the command history. The rejection of symbolic links is a basic preliminary check and does not completely prevent race conditions where a file is replaced just before reading.

Summary: Verifying in Two Stages: Syntax and Type

The fact that the TOML syntax is valid does not mean the configuration is as expected by the application.tomllibDefine the safely readable scope using , explicitly specify the required items and types, and upon failure, exit with an exit code without displaying values. This small procedure can be used as a mindset for pre-deployment configuration checks.

Samples and Official Documentation

• Daily Code Samples: Pre-inspection of TOML configurations

• Official Python Documentation: tomllib

• Official Python Documentation: argparse

• Official Python Documentation: unittest