Most Starlight failures are easier to solve when you classify them before changing files. Start with loader resolution, then direct incompatibilities, then world or lighting behavior. Changing several variables at once hides the cause.
1. Wrong Minecraft patch or loader
A Fabric build in Forge, a Forge build in Fabric, or a JAR built for a different patch version can fail before the game reaches the title screen. Verify the full file name and the profile version together.
2. Phosphor is installed at the same time
The original project explicitly describes Starlight and Phosphor as incompatible. Remove one of the two lighting-engine replacements and retest.
3. A source ZIP was placed in the mods folder
The homepage download is source code, not a compiled mod. A launcher cannot turn a source archive into a working mod simply because the filename contains “Starlight.”
4. Another mod touches chunk or lighting internals
Starlight is intentionally invasive. Conflicts can appear with mods that patch the same methods, alter chunk serialization, or make assumptions about vanilla light-section behavior.
Use a binary-search style test
On a copied profile, remove half of the suspect mods, test, then narrow the set until the interaction is isolated. Keep the world backup separate from the test instance.
5. Lighting looks wrong after a world change
Test a copied save, restart the client and server cleanly, and compare with a profile that uses the same world but not Starlight. Avoid repeatedly opening the only copy of an important world while diagnosing a low-level lighting issue.
6. Expected FPS improvement never appears
That may not be an error. The original 1.20 notes say Starlight and vanilla are close enough in some benchmark areas that certain older comparisons became unhelpful, and light-update time may be too small to change client FPS noticeably.
Related guides
Use the performance guide for better measurement and the Fabric setup guide for loader-specific checks.