The KMZ won't open: read the banner, then fix the file

Short answer: a KMZ is a KML file inside a zip, so the archive can only be one of four things, the viewer says which, and three of the four take one command to repair. The case that catches most people is the renamed archive — the file is fine, and the name is not.

Tested on 2 October 2026 in the KMZ viewer, in all three interface languages, with every fixture built from the commands at the end of this post. Every quoted string below is the tool's own. Each case here either shows a red banner and no layer, or a layer with a counts line and no banner — never both, so the screen already tells you which half of this post you are in.

A KMZ is a zip, so read the listing first

unzip -l site.kmz is the first move, and the KML and KMZ guide says so too, under the heading "Open or view a KMZ file online without Google Earth". This post is what to do with each of its four answers: a KML entry under a .kmz name, a KML entry under some other name, no KML entry at all, or a listing that fails because the thing is not an archive.

The control for everything below is one archive built by hand: a doc.kml holding one point, one line and one polygon, zipped with zip -X site.kmz doc.kml. It opens with no banner, the layer panel reads 1 polygon · 1 line · 1 point, and the layer is labelled with the KML's own document name, not the file name. That is the shape of a success — a counts line, nothing red.

The renamed .zip: the name decides, not the bytes

Copy that same archive to a second name with cp site.kmz site.zip and you have two files that are byte-for-byte identical. The .kmz opens. The .zip is refused, and the banner reads This ZIP contains a KML file. Rename it to .kmz, or extract the .kml, and load it again.

That is all of it: the loader decides what a file is from its extension before anything reads a byte, and .zip means a zipped shapefile. So your archive goes to the shapefile parser, which refuses it — there is no .shp in there. What you read is not that parser's complaint, though: having been refused, the viewer re-opens the archive, sees that it does hold a KML, and restates the refusal as the repair you need. The file is still refused; the sentence is about your file rather than about shapefiles.

The name is doing all of that work, which is clearest from the other side. The loader has a second way in — fetching a file from a link — and it passes no file name along: it invents one, remote.kmz when the link ends in .kmz or the response declares itself a zip, then calls the same dispatch. The same bytes would be accepted under the invented name and refused under yours, so the .zip branch is unreachable that way. One dispatch, two entry points, one name nobody chose. That inconsistency is ours and it is on our list rather than fixed; it is also not a workaround, because the viewer has no field to paste a link into. Correcting the name is the repair.

A zip with no KML inside

Build one with zip -X nokml.kmz readme.txt and drop it. The banner reads No KML file found inside the ZIP.

This one is named .kmz, so the KMZ path did run: the archive opened, the viewer went through the entries, and there was nothing to parse. The previous banner can be more specific because there, it found something.

A nested KML opens, and that surprises people

Put the KML somewhere other than the root — mkdir layers && cp doc.kml layers/site.kml && zip -X nested.kmz layers/site.kml — and the archive holds no doc.kml and no root-level entry at all. It opens. No banner, the same 1 polygon · 1 line · 1 point counts line, the same document name on the layer.

The rule the viewer applies is the first entry whose name ends in .kml, anywhere in the archive, below the root or not, lower-cased before that test, so DOC.KML opens too. A doc.kml sitting in the archive root is a convention — Google Earth's, and a good habit for a file you hand to someone else — not something this viewer requires. If your KMZ was refused, how deeply the KML sits is not the reason.

Not a zip, or not an extension the viewer knows

head -c 512 /dev/urandom > broken.kmz makes a file with a KMZ name and no archive inside it. The banner reads Error processing file. Make sure it is a valid KML or KMZ file. A truncated download lands here, and so does an error page a server returned under the name you asked for: file broken.kmz answers data rather than naming a zip archive, and unzip -l on it fails outright.

Copy those same bytes to broken.dat, or to a name with no extension at all, and the answer changes to Unsupported file type. Use KML or KMZ. Nothing read the bytes this time: the extension is checked twice, once to choose a parser and once inside the KML path, and one that neither check recognises is refused before any parse is attempted.

Fixing it, three ways

• Rename it back: mv site.zip site.kmz, then drop it on the viewer again. For a renamed archive that is the whole repair.
• Rebuild the archive: zip -X site.kmz doc.kml, from the directory holding the KML. Use this when the zip came from somewhere you do not control.
• Skip the container: unzip -o site.kmz '*.kml' and load the extracted .kml instead. The viewer takes a bare KML, and unzip ignores the archive's name, so this works on the renamed file too.

None of those converts anything, because none of these failures is about the contents. For the ones that are — attributes dropped on read, styles lost in conversion — the guide's "Errors, decoded" section has the transcripts.

Test files you can use

Nothing is hosted; each fixture is one or two commands. Build the KML first, as a UTF-8 doc.kml: <?xml version="1.0" encoding="UTF-8"?>, then <kml xmlns="http://www.opengis.net/kml/2.2"><Document><name>KMZ test</name>, then the three placemarks, then </Document></kml>. The coordinates are decimal degrees on purpose.

• <Placemark><name>P1</name><Point><coordinates>-46.633,-23.550,0</coordinates></Point></Placemark>
• <Placemark><name>L1</name><LineString><coordinates>-46.64,-23.55,0 -46.63,-23.54,0</coordinates></LineString></Placemark>
• <Placemark><name>A1</name><Polygon><outerBoundaryIs><LinearRing><coordinates>-46.65,-23.56,0 -46.64,-23.56,0 -46.64,-23.55,0 -46.65,-23.56,0</coordinates></LinearRing></outerBoundaryIs></Polygon></Placemark>

Then the six archives, in order: the control, zip -X site.kmz doc.kml · the same bytes under a second name, cp site.kmz site.zip · an archive with no KML in it, printf 'no KML here\n' > readme.txt && zip -X nokml.kmz readme.txt · a KML below the root, mkdir layers && cp doc.kml layers/site.kml && zip -X nested.kmz layers/site.kml · something that is not an archive, head -c 512 /dev/urandom > broken.kmz · and that same non-archive under an unknown extension, cp broken.kmz broken.dat. Check one first: unzip -l nested.kmz lists a single entry, layers/site.kml.

For teams

"The KMZ won't open" is usually a handover problem rather than a file problem: the archive was renamed to get past a mail filter, or rebuilt by a tool that moved the KML, and whoever has to open it is not whoever made it. Geodocs keeps field data on one shared map instead of one KMZ per phone, so there is no archive to rename and nothing to re-zip.