Faltou o .shx ou o .dbf: Por Que o Shapefile Não Abre (e o Que Cada Arquivo Faz)
Três arquivos formam o Shapefile: .shp, .shx e .dbf. Tudo mais com o mesmo nome-base (.prj, .cpg, .sbn, .qix, .shp.xml) é um arquivo-satélite. Quando "o Shapefile não abre", um dos três está faltando, e qual deles decide o que você vê: sem .shx o GDAL recusa enquanto o navegador abre o arquivo como se nada tivesse acontecido; sem .dbf tudo abre com zero atributos e sem aviso; sem .shp não há nada para abrir. Abaixo, o que cada arquivo é, se você pode reconstruí-lo, e o que o shapefile-viewer e o ogrinfo dizem quando ele está faltando.
Testado em 16 de setembro de 2026 contra o shapefile-viewer ao vivo em static-page-tools@442f8d8 e o GDAL 3.13.3 "Iowa City", nos limites estaduais de 2022 do IBGE (27 polígonos, cinco campos), enviados como zip e como arquivos soltos. A seção "O que é um Shapefile" do guia de Shapefile descreve cada arquivo byte a byte; este post é sobre o que quebra.
Um parágrafo por arquivo
.shp é a geometria: cada registro é um código de tipo de forma seguido de coordenadas. Obrigatório, porque é o dado em si, e não é reconstruível a partir de mais nada. No navegador é o único arquivo que precisa existir.
.shx é um índice de largura fixa: para cada registro, o seu deslocamento em bytes dentro do .shp. A especificação de 1998 o chama de obrigatório e o GDAL trata assim; o navegador nunca o lê (o parser shpjs percorre o .shp sequencialmente). É uma função pura do .shp, então é totalmente reconstruível: o GDAL reconstruiu o .shx de 316 bytes do IBGE byte a byte idêntico ao original (caso 2).
.dbf é a tabela de atributos, em formato dBASE; o registro n no .dbf é a feição n no .shp. A especificação o chama de obrigatório, mas o GDAL e o navegador abrem a camada sem ele, em silêncio, com zero campos. Não é reconstruível: os atributos não existem em nenhum outro lugar.
.prj é um arquivo de texto de uma linha com o sistema de referência de coordenadas em WKT. Opcional na especificação, obrigatório na prática: sem ele o GDAL relata Layer SRS WKT: como (unknown) e nada sabe se os números são graus ou metros. Reconstruível apenas se você souber o CRS (ogr2ogr -a_srs), o assunto do primeiro post desta série.
.cpg é um arquivo de uma linha que nomeia a codificação do .dbf (o do IBGE diz UTF-8, cinco bytes). Opcional; reconstruível se você souber a codificação (echo UTF-8 > BR_UF_2022.cpg). O segundo post desta série é sobre o que dá errado sem ele.
.sbn e .sbx (o índice espacial da ESRI, escrito pelo ArcGIS e nunca pelo GDAL), .qix (o índice espacial aberto do GDAL, QGIS e MapServer) e .shp.xml (metadados do ArcGIS) são opcionais, reconstruíveis ou descartáveis, e nenhum deles é lido pelo visualizador no navegador.
O que você vê para cada arquivo faltando
O conjunto completo (caso 1)
Zip e arquivos soltos dão a mesma linha no visualizador: 27 polígonos e 5 campos, CRS GCS_SIRGAS_2000 em Detalhes, GeoJSON exportado começando em [-68.7928173712301, -10.999569659337354]. GDAL: Feature Count: 27, GEOGCRS["SIRGAS 2000", cinco campos. Cada caso abaixo é este conjunto menos um arquivo; "abre" significa que a linha e a exportação são idênticas a esta.
Sem o .shx (caso 2)
No visualizador, nada muda. Zip ou solto, a linha e a exportação são idênticas ao conjunto completo. O parser nunca abre o .shx, e o caminho de arquivos soltos nem sequer procura por um, então o navegador é uma forma rápida de confirmar que o .shp em si está saudável.
O GDAL recusa, e diz por quê: ERROR 4: Unable to open cases/2-no-shx/BR_UF_2022.shx or cases/2-no-shx/BR_UF_2022.SHX. Set SHAPE_RESTORE_SHX config option to YES to restore or create it. A correção é a que ele mesmo indica: ogrinfo -so BR_UF_2022.shp BR_UF_2022 --config SHAPE_RESTORE_SHX YES abre a camada (27 registros, cinco campos) e um BR_UF_2022.shx de 316 bytes aparece ao lado do .shp. Comparado com o original do IBGE usando cmp: byte a byte idêntico. SHAPE_RESTORE_SHX é uma opção --config, não uma opção de abertura do driver. A seção "Erros, decodificados" do guia de Shapefile cita a mesma linha.
Sem o .dbf (caso 3)
O visualizador abre e não diz nada. A linha mostra 27 polígonos e 0 campos, o CRS é exibido, não há aviso, e a exportação é a mesma geometria com "properties": null em cada feição; zip e solto se comportam de forma idêntica. A própria descrição da ferramenta admite isso: "Um .shp avulso exibe apenas a geometria, sem atributos."
O GDAL também abre e não diz nada. ogrinfo -so imprime Feature Count: 27 e o CRS sem linhas de campo e sem os metadados DBF_DATE_LAST_UPDATE; -fid 0 imprime o polígono sem atributos. Não há correção: o .dbf não pode ser reconstruído a partir da geometria, então peça o conjunto completo para quem exportou a camada.
Sem o .shp (caso 4)
O visualizador para com um aviso: Nenhum arquivo .shp encontrado. Arraste um .shp ou um ZIP contendo um. A mesma mensagem aparece quer os arquivos restantes cheguem como zip ou como arquivos soltos.
O GDAL não consegue abrir a camada (ogrinfo BR_UF_2022.shp termina em No such file or directory), mas abre o .dbf órfão como uma tabela: ogrinfo BR_UF_2022.dbf relata Geometry: None, Feature Count: 27, Layer SRS WKT: (unknown) e os cinco campos, e -fid 0 imprime NM_UF (String) = Acre. Os atributos sobrevivem à perda do .shp; a geometria não.
Sem o .prj (caso 5)
Um .prj faltando é uma falha diferente, a camada abre e nada sabe o que as suas coordenadas significam, e tem seu próprio post: Shapefile no lugar errado: faltou o .prj.
.cpg faltando ou errado (caso 6)
Um .cpg faltando ou errado não impede nada de abrir; ele transforma acentos em é, e esse é o segundo post: Shapefile com acentos errados: .cpg, Latin-1 e UTF-8.
O zip do macOS (caso 7)
Um zip feito no Finder carrega uma pasta __MACOSX/ com um arquivo ._BR_UF_2022.shp de metadados para cada arquivo (dados de resource fork do Finder, não uma cópia). O visualizador ignora toda entrada __MACOSX, então um zip cujo único .shp é esse arquivo de metadados recebe o mesmo aviso do caso 4: Nenhum arquivo .shp encontrado. Arraste um .shp ou um ZIP contendo um. Com os arquivos reais ao lado da pasta (o zip comum do Finder) ele abre exatamente como o conjunto completo. O GDAL concorda: o zip só com os arquivos de metadados é not recognized as being in a supported file format; o completo lista BR_UF_2022 (Polygon) via /vsizip/.
Quando o aviso está mentindo (caso 8)
Uma nota de honestidade: para um zip, o visualizador relata qualquer falha do parser como "Nenhum arquivo .shp encontrado", incluindo um .prj que o parser não consegue ler e um tipo de forma que ele não conhece. Se você tem certeza de que o .shp está ali, suspeite primeiro do .prj. O GDAL, por sua vez, abre os mesmos arquivos e não imprime aviso nenhum: ele trata em silêncio um .prj ilegível como ausente e relata Layer SRS WKT: como (unknown); só o gdalsrsinfo BR_UF_2022.prj nomeia o problema (ERROR 1: missing [).
Arquivos de teste que você pode usar
O conjunto de dados: 13.717.460 bytes, SHA-256 282ec7f0f0beeeead45e6609f4ffffce161bda04cb8ee0afcad2316d1c841bcb, SIRGAS 2000 (EPSG:4674). A listagem do diretório não imprime linha de licença; credite o IBGE e confira os termos do portal.
Para reproduzir qualquer caso acima, descompacte o zip, apague um dos arquivos, e solte o resto no visualizador (ou recompacte com zip -j para que nenhuma pasta seja adicionada):
unzip -o BR_UF_2022.zip(cinco arquivos:.cpg,.dbf,.prj,.shp,.shx).rm BR_UF_2022.shxpara o caso 2,rm BR_UF_2022.dbfpara o caso 3,rm BR_UF_2022.shppara o caso 4.
Se os atributos abrem mas os nomes das colunas parecem cortados, isso não é um arquivo faltando e sim o limite de 10 caracteres do formato, o terceiro post desta série: Nomes de coluna do Shapefile cortados em 10 caracteres.
Para times
Encontrar o arquivo que falta é a metade fácil. Alguém te mandou um Shapefile porque um time precisa fazer algo com aqueles polígonos: um status por feição, fotos e um formulário vindos do campo, um relatório até sexta. O Geodocs importa o mesmo conjunto para um mapa do time, mantém as colunas do .dbf como campos que o time preenche, roda a revisão e produz o relatório com o mapa dentro. O visualizador é onde você confere o arquivo; o workspace é onde ele vira trabalho.