Ошибки загрузки

Ошибки загрузки в Mapbox GL JS возникают на нескольких уровнях: от сетевых запросов до рендеринга WebGL. Архитектура библиотеки опирается на загрузку стиля, тайлов, шрифтов (glyphs), спрайтов и данных векторных источников, поэтому сбой в любом звене приводит к частично или полностью неработоспособной карте.

При инициализации карты выполняется последовательная цепочка:

  • загрузка style JSON
  • загрузка sprite (иконки)
  • загрузка glyphs (шрифты)
  • загрузка vector/raster tiles
  • инициализация WebGL контекста
  • отрисовка слоёв

Каждый этап генерирует собственные события и ошибки, которые фиксируются через map.on('error', ...) или через консоль браузера.

Ошибки загрузки style (style.load / styledata)

Стиль является центральным описанием карты. Он содержит ссылки на источники данных и ресурсы.

Типовые причины ошибок:

Неверный URL стиля

  • 404 Not Found — стиль удалён или путь указан неверно
  • опечатка в mapbox://styles/...
  • использование приватного стиля без доступа

Ошибки авторизации

  • 401 Unauthorized — отсутствует или некорректен access token Mapbox
  • токен не имеет доступа к стилю (scope mismatch)

Некорректный JSON стиля

  • синтаксические ошибки
  • отсутствующие обязательные поля (version, sources, layers)
  • неверные типы данных в слоях

Диагностика обычно начинается с:

  • проверки ответа Network tab
  • логирования map.on('style.load') и отсутствия его вызова

Ошибки загрузки тайлов (tiles)

Тайлы — основной источник геоданных.

HTTP-ошибки

  • 404 — отсутствует тайл в источнике (неполный tileset)
  • 403 — доступ запрещён (приватный tileset или ограниченный токен)
  • 429 — превышен rate limit API

Геометрические причины

  • запрошенный zoom вне диапазона minzoom/maxzoom
  • отсутствие данных в конкретной зоне
  • неверно настроенный source tiles или url

Повторные запросы и перегрузка

Mapbox GL JS автоматически ретраит запросы, но при высокой нагрузке:

  • увеличивается latency
  • появляются “popping” эффекты при подгрузке
  • возможны частичные пустые тайлы

Ошибки glyphs (шрифты)

Glyphs критичны для отображения текста.

Типовые проблемы:

  • неправильный URL glyphs в стиле
  • отсутствие PBF файлов на сервере
  • CORS блокировка
  • 404 для конкретных диапазонов символов

Симптомы:

  • пустые подписи
  • квадратные символы вместо текста
  • частично отрисованные labels

Часто проблема проявляется только на определённых языках (кириллица, иероглифы), так как они требуют расширенных диапазонов glyph ranges.

Ошибки sprite (иконки)

Sprite содержит изображения для слоёв символов.

Причины сбоев:

  • отсутствует sprite.json или .png
  • несоответствие версий стиля и sprite
  • CORS ограничения при загрузке с CDN
  • неверный base URL

Симптом:

  • отсутствуют иконки POI
  • слои symbol отображаются пустыми

WebGL ошибки и контекст рендеринга

Mapbox GL JS зависит от WebGL.

Типовые проблемы:

  • WebGL context lost
  • неподдерживаемая видеокарта
  • ограничения браузера в iframe
  • слишком большое количество слоёв

Причины:

  • перегрузка GPU памятью (большие GeoJSON)
  • одновременное использование нескольких WebGL контекстов
  • отключённое аппаратное ускорение

Обработка:

  • событие webglcontextlost
  • пересоздание карты при необходимости

Ошибка события error

Центральный механизм диагностики:

map.on('error', (e) => {
  console.log(e.error);
});

Типы объектов ошибок:

  • StyleError
  • TileError
  • SourceError
  • сетевые исключения

Ключевая проблема — часть ошибок не прерывает работу карты, а только деградирует слой.

Ошибки загрузки источников (sources)

Источники данных определяют структуру карты.

GeoJSON ошибки:

  • некорректный JSON
  • слишком большие объекты (> мегабайт)
  • неверная структура FeatureCollection

Vector tile sources:

  • неверный tiles URL
  • несоответствие scheme (xyz vs tms)
  • отсутствующий tilejson

CORS и ограничения безопасности

При загрузке ресурсов с внешних доменов возникают:

  • блокировка браузером
  • отсутствие Access-Control-Allow-Origin
  • проблемы с credentials mode

Особенно критично для:

  • sprite
  • glyphs
  • raster tiles

Решения обычно находятся на уровне сервера, а не клиента.

Ошибки токенов доступа

В экосистеме Mapbox access token управляет доступом ко всем ресурсам.

Типовые ошибки:

  • просроченный токен
  • ограничение по домену (URL restrictions)
  • недостаточные scopes (styles:read, tiles:read)
  • превышение лимита запросов

Диагностируется через:

  • HTTP статус ответа
  • Unauthorized в консоли

Ошибки загрузки стиля по этапам

Стиль проходит несколько фаз:

  1. style.load
  2. styledata
  3. sourcedata
  4. render
  5. idle

Сбой на любом этапе даёт разные симптомы:

  • нет style.load → стиль не загружен
  • нет idle → бесконечная загрузка
  • нет sourcedata → проблемы с тайлами

transformRequest и модификация запросов

Функция transformRequest часто становится источником скрытых ошибок:

  • неправильное добавление headers
  • поломка URL параметров
  • случайное удаление токена

Пример проблем:

  • запросы начинают возвращать 401 после кастомного transform
  • sprite/glyph endpoints становятся недоступными

Кэширование и устаревшие ресурсы

Ошибки могут быть связаны не с сетью, а с кэшем:

  • устаревший style JSON
  • несовместимая версия sprite
  • cached tiles с другим schema

Особенно проявляется при:

  • смене версии стиля
  • миграции tileset

Диагностика через DevTools

Ключевые точки анализа:

  • Network → фильтр по .pbf, .png, .json
  • Console → ошибки Mapbox GL
  • Performance → GPU bottlenecks
  • Application → cache storage

Полезно отслеживать:

  • статус каждого tile request
  • размер payload
  • время ответа

Типовые каскадные ошибки

Одна первичная ошибка часто вызывает цепочку:

  • неверный token →

    • 401 tiles →
    • пустые слои →
    • ошибки glyphs →
    • отсутствие labels

или:

  • CORS sprite →

    • missing icons →
    • warning в style validation →
    • частичная деградация UI

Стратегии устойчивости

При проектировании систем с Mapbox GL JS обычно закладываются механизмы:

  • fallback styles (резервный стиль без сложных слоёв)
  • retry logic на уровне fetch
  • локальное кеширование tiles
  • graceful degradation (без glyphs/sprites)
  • мониторинг map.on('error')

Ошибки и события загрузки как система сигналов

Система ошибок не является бинарной. Она отражает состояние графа загрузки:

  • style → структура карты
  • sources → данные
  • tiles → детализация
  • glyphs/sprites → визуальный слой

Нарушение любого узла приводит не к падению, а к частичной деградации визуализации, что требует анализа по слоям, а не по единому исключению.

Оглавление