Ошибка «невозможно разрешить библиотеку плейсхолдера» (в англоязычном интерфейсе Android Studio она обычно звучит как «Unable to resolve placeholder library» или «Failed to resolve…») возникает на этапе синхронизации Gradle и означает, что система сборки не смогла найти или подставить зависимость, указанную в конфигурации проекта. Чаще всего первый признак — красная строка в окне Build и остановка синхронизации сразу после открытия проекта или добавления новой библиотеки.
Проблема почти всегда связана не с кодом приложения, а с конфигурацией: файлом build.gradle, настройками репозиториев, версией плагина Android Gradle Plugin или плейсхолдерами манифеста (manifest placeholders), которые подставляются в AndroidManifest.xml во время сборки. Ниже разберём, как локализовать источник сбоя и исправить его безопасными способами.
Что означает эта ошибка на самом деле
Термин «плейсхолдер» в контексте сборки Android-проекта имеет два значения, и важно понять, о каком из них идёт речь в вашем случае. Первое — плейсхолдер зависимости: когда в блоке dependencies указана библиотека, которую Gradle не может найти ни в одном из подключённых репозиториев. Второе — плейсхолдер манифеста: переменная вида ${имя} в AndroidManifest.xml, значение которой должно быть задано через manifestPlaceholders в build.gradle.
Быстрая проверка: откройте полный текст ошибки в окне Build или на вкладке Problems. Если в сообщении фигурирует координата вида group:artifact:version — проблема в зависимости. Если упоминается AndroidManifest.xml и имя переменной — ищите незаданный плейсхолдер манифеста.
Типичные причины сбоя
Прежде чем что-то менять, полезно понять, какие ситуации приводят к такой ошибке чаще всего. Это сократит круг проверок.
- 🔍 Опечатка в координатах библиотеки — неверное имя группы, артефакта или несуществующая версия в блоке
dependencies. - 🌐 Отсутствует нужный репозиторий — библиотека опубликована, например, в Maven Central или Google Maven, но соответствующий репозиторий не объявлен в проекте.
- 📦 Незаданный плейсхолдер манифеста — в
AndroidManifest.xmlиспользуется переменная, для которой не указано значение вmanifestPlaceholders. - 🔌 Нет доступа к сети или повреждён кэш Gradle — зависимость не может быть скачана, а локальная копия отсутствует или испорчена.
- ⚙️ Несовместимость версий — устаревший плагин Android Gradle Plugin или версия Gradle не поддерживает синтаксис конфигурации.
⚠️ Внимание: не удаляйте строки из build.gradle «наугад», чтобы заставить синхронизацию пройти. Удалённая зависимость может незаметно сломать функциональность приложения, и ошибка всплывёт уже на этапе выполнения.
Шаг 1. Проверка зависимостей и репозиториев
Откройте файл build.gradle уровня модуля (обычно app) и найдите строку с библиотекой, которая указана в тексте ошибки. Сверьте координаты с официальной документацией библиотеки: имя группы, артефакта и номер версии должны совпадать символ в символ. Обратите внимание на регистр букв и дефисы — система координат Maven чувствительна к ним.
Затем проверьте, объявлены ли репозитории, в которых опубликована библиотека. В зависимости от версии проекта список репозиториев находится либо в build.gradle уровня проекта, либо в файле settings.gradle в блоке dependencyResolutionManagement. Типичная конфигурация выглядит так:
repositories {
google()
mavenCentral()
}
Если библиотека распространяется через собственный репозиторий разработчика, его адрес нужно добавить в этот список — точный URL берите только из официальной документации конкретной библиотеки.
☑️ Проверка зависимостей
Шаг 2. Проверка плейсхолдеров манифеста
Если ошибка указывает на AndroidManifest.xml, откройте файл и найдите все вхождения конструкции ${...}. Каждая такая переменная должна получать значение при сборке. Значения задаются в build.gradle модуля внутри блока defaultConfig или конкретного buildType:
android {
defaultConfig {
manifestPlaceholders = [appLabel: "MyApp"]
}
}
Частый сценарий: библиотека, которую вы подключили, содержит в собственном манифесте плейсхолдер (например, ключ API или имя приложения), а её документация требует задать значение в вашем проекте. Если значение не задано, инструмент слияния манифестов (manifest merger) завершается с ошибкой. Решение — добавить соответствующий ключ в manifestPlaceholders, следуя инструкции именно вашей библиотеки.
Шаг 3. Очистка кэша и повторная синхронизация
Повреждённый кэш — нетривиальная, но реальная причина: Gradle хранит скачанные зависимости локально, и если загрузка оборвалась, система может считать библиотеку «отсутствующей», даже когда всё настроено верно. Вам нужно выполнить очистку через меню File → Invalidate Caches… в Android Studio и перезапустить IDE.
Если это не помогло, попробуйте пересобрать проект из терминала, чтобы увидеть полный и нефильтрованный вывод:
gradlew clean build --refresh-dependenciesФлаг --refresh-dependencies заставляет Gradle заново проверить и скачать зависимости, игнорируя закэшированные данные. Команда выполняется из корневой папки проекта; в Windows вместо gradlew используется gradlew.bat.
⚠️ Внимание: очистка кэша и повторная загрузка зависимостей требуют стабильного интернет-соединения. Если вы работаете через корпоративный прокси или VPN, убедитесь, что Gradle настроен на его использование — иначе скачивание снова завершится неудачей.
Сравнение типовых сценариев ошибки
Таблица ниже поможет быстро сопоставить симптом с вероятной причиной и первым действием.
| Фрагмент текста ошибки | Вероятная причина | Первое действие |
|---|---|---|
| Failed to resolve: group:artifact:version | Опечатка в координатах или отсутствует репозиторий | Сверить координаты с документацией библиотеки |
| Attribute ... requires a placeholder substitution | Незаданный плейсхолдер манифеста | Добавить значение в manifestPlaceholders |
| Could not GET / Could not HEAD | Нет сети, прокси или репозиторий недоступен | Проверить интернет и настройки прокси Gradle |
| Unsupported / incompatible Gradle version | Несовместимость версий Gradle и плагина | Сверить версии с таблицей совместимости в официальной документации |
Когда проблема в версиях Gradle и плагина
После обновления Android Studio среда может предложить обновить и Android Gradle Plugin, однако не каждая версия плагина совместима с каждой версией Gradle. Несоответствие проявляется именно ошибками разрешения конфигурации. Версия Gradle задаётся в файле gradle/wrapper/gradle-wrapper.properties, версия плагина — в build.gradle уровня проекта или в каталоге версий libs.versions.toml.
Как действовать аккуратно: не повышайте версии вслепую. Откройте официальную таблицу совместимости Android Gradle Plugin и Gradle на сайте документации Android и приведите обе версии в соответствие с ней. Если проект старый и обновление невозможно, иногда разумнее откатить версию плагина до той, с которой проект собирался ранее.
Что делать, если проект чужой или унаследованный
Начните с поиска файла README или документации в репозитории — там часто указаны требуемые версии JDK, Gradle и плагина. Проверьте, какая версия JDK выбрана в настройках Android Studio (Settings → Build, Execution, Deployment → Build Tools → Gradle): несовместимая версия Java тоже вызывает сбои конфигурации. Если в проекте есть CI-конфигурация (GitHub Actions, GitLab CI), посмотрите в ней — там обычно зафиксировано рабочее окружение сборки.
Если ничего не помогло
Когда стандартные шаги исчерпаны, остаётся несколько безопасных вариантов. Первый — создать новый пустой проект в Android Studio и перенести в него конфигурацию по частям: так вы найдёте строку, которая ломает сборку, методом исключения. Второй — сравнить ваши файлы build.gradle и settings.gradle с эталонным рабочим проектом той же команды или с шаблоном, который генерирует актуальная версия IDE.
Третий вариант — изучить полный стек ошибки с расширенным логированием:
gradlew build --stacktraceВывод будет длинным, но именно в нём видно, какой именно файл и какая строка конфигурации вызвали сбой. Копируйте текст ошибки целиком, а не только первую строку — решающая информация почти всегда находится в блоке «Caused by» ниже по тексту.
⚠️ Внимание: избегайте советов из сети вроде «добавьте эту строку в gradle.properties» или «отключите проверку зависимостей», если вы не понимаете, что делает параметр. Обходные пути могут скрыть ошибку, но вернуться в виде сбоев уже в готовом приложении.
Часто задаваемые вопросы
Ошибка появилась сразу после добавления новой библиотеки. Что проверить в первую очередь?
Сверьте координаты зависимости с официальной документацией библиотеки и убедитесь, что нужный репозиторий объявлен в проекте. Также проверьте, не требует ли библиотека задать плейсхолдер манифеста или дополнительные параметры в build.gradle.
Синхронизация проходит, но ошибка возникает при сборке APK. Почему?
Это характерно для проблем слияния манифестов: плейсхолдер подставляется на этапе сборки, а не синхронизации. Откройте полный лог сборки и найдите упоминание AndroidManifest.xml и имени незаданной переменной.
Поможет ли переустановка Android Studio?
Практически никогда: ошибка находится в конфигурации проекта или кэше Gradle, а не в самой IDE. Переустановка лишь удалит настройки, не устранив причину. Начните с очистки кэша и проверки файлов build.gradle.
Может ли ошибка быть вызвана отсутствием интернета?
Да, если зависимость ещё не скачана в локальный кэш. Gradle не сможет её разрешить без сети. Проверьте подключение и настройки прокси, затем выполните синхронизацию повторно.
Где искать точный текст ошибки, если окно Build показывает мало информации?
Запустите сборку из терминала командой gradlew build --stacktrace из корня проекта. Консольный вывод содержит полную цепочку причин, включая блоки «Caused by», которых нет в сокращённом отображении IDE.