How to read a compile log: VBSP, VVIS and VRAD in Hammer

Q: Where do I find the compile log after the window is closed?

The compile tools write the log to .log next to your VMF. You can open the file in any text editor. GMod's tools append every new compile at the end of the file.

How to read a Hammer compile log: the VBSP, VVIS and VRAD sections, the messages that matter and how to find the first real cause of an error.

Published 7 October 20266 min read

You read a compile log from top to bottom and look for the first message that reports an error. The log has three sections, one each for VBSP, VVIS and VRAD, and most later messages are only consequences of the first problem. Once you can tell the three sections apart and know a handful of typical messages, you usually find the cause within minutes.

Where the log lives and how it is structured

Hammer shows the log in the compile window while it runs, and the compile tools also write it to <mapname>.log in the same folder as your VMF. GMod's tools do not replace this file but append to it, so the most recent compile is at the end. In the file, start reading where the last compile begins.

In the compile window of the bundled Hammer, each of the three tools starts with the block below; Hammer++ prints a line beginning with Running command: instead. The .log file has no such header, so there you tell the sections apart by the typical lines in the table:

** Executing...
** Command: "...\bin\vbsp.exe"
** Parameters: -game "...\garrysmod" "...\rp_example"

Section	Job	Typical lines on success
VBSP	Builds geometry, entities and portals from the VMF	`ProcessBlock_Thread`, `Building Faces`, `WriteBSP`
VVIS	Calculates which areas are visible from where	`BasePortalVis`, `PortalFlow`, `Average clusters visible`
VRAD	Calculates lightmaps and prop lighting	`BuildFacelights`, `GatherLight`, `FinalLightFace`

What the three tools do in detail is covered in VBSP, VVIS and VRAD explained. For reading the log, one rule is enough: each tool works with the output of the previous one. If VBSP fails, VVIS and VRAD have nothing usable to work with.

Error, warning or harmless

Not every conspicuous line is a problem. There are three levels.

Error: The tool stops or writes no usable output. If VBSP stops, no new BSP is created. Hammer then often reports The command failed during the final copy step, or the game starts with the old file and your changes are missing.
Warning: The tool keeps running, but the result is flawed in one spot. An example is WARNING: Too many light styles on a face from VRAD. The map works, but lighting is wrong at the reported position.
Harmless: A line such as Memory leak: mempool blocks left in memory, known from the logs of Source compile tools, has nothing to do with a leak in your map. It concerns the tool itself and can be ignored.

The most important messages and what they mean

Message	Section	Meaning	What you do
`** leaked **`	VBSP	The map is not sealed. An entity has a connection to the empty space outside. The next line names the entity and its coordinates.	Load the red line in Hammer via Map > Load Pointfile and follow it to the hole.
`areaportal brush doesn't touch two areas`	VBSP	An areaportal does not separate two areas, because they are still connected somewhere else. The line begins with the number of the brush.	Load the line via Map > Load Pointfile and close the connection that is still open between the areas.
`material ... not found`	VBSP	A material used in the VMF was not found in the game's search paths.	Check path and spelling, and make sure the content sits in the correct game folder.
`MAX_MAP_...` or `Too many ...`	VBSP, VRAD	An engine limit was exceeded, for example brush sides or planes.	Simplify geometry and move detail into models.
`LoadPortals: couldn't read`	VVIS	VBSP did not write a portal file. This is almost always the result of a leak.	Do not search here. Fix the leak in the VBSP section.
`The map overflows the max portal count`	VVIS	The map has more portals than VVIS can process, and the tool stops.	Turn small parts into `func_detail` and simplify the world geometry.
`No vis information, direct lighting only`	VRAD	VRAD received no visibility data and calculates without bounced light.	Look further up for the cause, usually a leak or a skipped VVIS run.

The most common cases have their own guides: fixing a map leak and Source engine map limits.

The table at the end of VRAD

At the very end, VRAD prints an overview of how full the individual data areas of the BSP are, such as brushes, planes or entities. If a line is marked VERY FULL!, you are close to a limit. On large maps, check this table after every full compile to spot bottlenecks early.

How to proceed: first error first

Check that all three tools ran. In the compile window, search for vbsp.exe, vvis.exe and vrad.exe; in the .log file, look for the typical lines from the table above.
Search from the top for leaked, Error, WARNING, failed and not found.
Fix only the first real error. Everything after it may be a consequence.
Compile again and read the log from the top once more. Only when the first error is gone do the remaining messages mean anything.
Then work through the warnings. Many messages name coordinates or a brush number. In Hammer, the View menu lets you jump straight to coordinates or to a brush number.
Finally, glance at the VRAD table to keep an eye on limits.

Let a tool evaluate the log

Long logs are tedious when you do not know the messages yet. The Map Scanner has a compile log mode for this: you paste a Hammer, VBSP, VVIS or VRAD log, or upload it as .txt or .log. The result is sorted into likely root causes, further errors, follow-up errors and warnings, each with a cause and steps to fix it. Messages the scanner does not know yet can be reported. The scanner is labelled as beta and free of charge.

If you want to look up a single message, use the error database. It contains reviewed error messages from Hammer and the compile tools with cause and solution.

FAQ

Where do I find the compile log after the window is closed?

The compile tools write the log to <mapname>.log next to your VMF. You can open the file in any text editor. GMod's tools append every new compile at the end of the file.

Do I have to fix every warning?

No. Warnings do not stop the compile, and some have no visible effect. You should fix warnings that name coordinates in playable areas, because lighting or visibility is usually visibly wrong there.

Why are my changes missing in game although the compile finished?

Most likely VBSP stopped and no new BSP was written. The game then loads the older file. Look for the first error message in the VBSP section.

What does "Memory leak: mempool blocks left in memory" mean?

The line comes from Source compile tools and describes memory that the tool did not release when it exited. It has nothing to do with a leak in the map, and you do not need to do anything. In our test compiles with GMod's current tools it did not appear.