← All notes

May 2026

Debugging a boot crash on a corrupted settings file

A service that refuses to start on a malformed settings file. Read the real stack trace instead of guessing, isolate the bad JSON, regenerate it.

A service crashes at startup and never comes up. The reflex is to test random hypotheses: permissions, port, a missing dependency. That is the slowest path. The cause is almost always already written in the logs.

Read the stack trace, do not guess it

Open the startup log and read the full trace, not just the last line. The exception type and the file at fault are in there. A crash on a JSON parse points to the file and often to the position of the offending character.

Guessing makes you test ten leads unrelated to the problem. The trace gives the answer in one read: this parser failed on this file, at this offset.

Isolate the file, then regenerate it

Once the file is identified, validate it outside the service with a strict parser. The error flags the exact spot: a trailing comma, an unclosed brace, a write truncated halfway by an abrupt shutdown.

If the file is generated by the application, the cleanest move is to delete or rename it and let the service regenerate it from its defaults. Avoid hand-repairing a file the code already knows how to rebuild.

The principle: the trace is the source of truth. Read it first, isolate the faulty file, regenerate it rather than patch it by hand.