Устранение неполадок
Что делать, если агент не подключается, задание ждёт в очереди, шаг упал, SBOM не построен или файлы не загрузились — по кодам ошибок и сообщениям.
Где искать причину:
| Что | Где |
|---|---|
| Почему задание ждёт | Страница запуска → репозиторий: баннер с причиной ожидания и местом в очереди |
| Почему шаг упал | Доска стадий: значок шага, код выхода, подсказка с ошибкой; вкладка Логи |
| Почему нет находок или SBOM | Вкладка Файлы: файлы попытки, ошибки загрузки, предупреждения разбора отчётов |
| Состояние агента | Workflow → Раннеры: статус, экземпляры, история попыток |
| Журнал агента | docker compose logs scan-agent или kubectl logs <pod> -c agent; встроенный агент — docker compose --profile scan-agent logs scan-agent в каталоге сервера |
Запуск не создаётся
| Сообщение в форме | Код | Что делать |
|---|---|---|
| Нет подходящего агента | no_matching_agent (409) | Нет ни одного агента с метками из agent.labels шаблона, нужным исполнителем и (если у агента задан список) разрешённым шаблоном. Текст ошибки называет метки и исполнитель. Добавьте агента или поправьте метки в Workflow → Раннеры. Выключенный или не подключённый агент запуск не блокирует — задание подождёт его в очереди. |
| Хранилище результатов недоступно | storage_unavailable (503) | Результатам некуда попасть: на сервере не заданы FILES_S3_* (S3 комплекта), и своего включённого S3 нет. Задайте FILES_S3_* или подключите своё хранилище в Настройки → Интеграции → S3-хранилище (см. S3-хранилище). |
| Проверьте параметры запуска | 400 | Значение параметра не прошло проверку: нет обязательного, не подходит под pattern, не входит в choices, содержит перевод строки. |
| Шаблону «…» не хватает секретов или подключений | 400 | Шаблон ссылается на секрет, файл конфигурации, интеграцию или registry Nexus, которых нет или которые выключены. Список — в тексте ошибки. |
| Ни один репозиторий нельзя просканировать | 400 | Ни один выбранный репозиторий не прошёл проверку: нет ветки для сканирования или недопустимое имя ветки, либо у репозитория без подключения Bitbucket/GitHub адрес не подходит для анонимного клона (нужен https://; адрес http:// годится, если у включённого подключения GitLab или Gitea тот же протокол, хост и порт). Причина для каждого — в тексте ошибки. Если не прошла только часть репозиториев, запуск создаётся, а они отмечаются «Не запущено: …». |
| Шаблон пайплайна «…» выключен | 400 | Включите шаблон в Workflow → Пайплайны. |
| Недостаточно прав | 403 | Шаблон с политикой «Администраторы» или нет прав на выбранные репозитории. |
| Лицензия в режиме только чтения | 402 | Продлите лицензию: Настройки → Лицензия. |
Задание ждёт в очереди
Пока задание в очереди, страница запуска показывает причину:
| Причина | Код | Что проверить |
|---|---|---|
| Нет агента с подходящими метками/исполнителем | no_matching_agent | Метки агента (задаёт администратор) должны включать все agent.labels шаблона. Шаблоны с image, network: none, resources, user, sourceReadOnly требуют исполнитель docker. У агента может быть ограничен список разрешённых пайплайнов. |
| Все подходящие агенты отключены администратором | matching_agents_disabled | Включите агента в Workflow → Раннеры. |
| Подходящие агенты не в сети | matching_agents_offline | Ни один экземпляр не присылал heartbeat последние 90 секунд. Смотрите журнал агента и раздел Агент не подключается. |
| Все подходящие агенты заняты | matching_agents_busy | Все слоты заняты. Задание подождёт. Чтобы ускорить, поднимите ARCHEPELAG_AGENT_CONCURRENCY или число экземпляров. |
Задание ждёт не дольше agent.queueTimeoutMinutes шаблона (по умолчанию сутки). Потом оно завершается ошибкой с той же причиной, например «Нет агента с метками docker и исполнителем docker — задание ждало в очереди дольше 1440 мин».
Агент онлайн, слоты свободны, но заданий не берёт:
- Мало места. В рабочем каталоге свободно меньше
ARCHEPELAG_AGENT_MIN_FREE_GB(по умолчанию 10 ГБ). В журнале агента:Not enough free disk space — not claiming jobs. - Runner не готов (режим shell). В журнале:
Waiting for the shell runner sidecar. Проверьте контейнерrunnerи общий каталог/work. Runner вCrashLoopBackOffв Deployment — он не должен выходить между заданиями:ARCHEPELAG_RUNNER_EXIT_AFTER_JOB=trueдопустим только вkeda-scaledjob.yaml; причину падения покажетkubectl logs <pod> -c runner --previous.
Агент не подключается
| Симптом | Причина и решение |
|---|---|
Некорректные настройки агента при старте | Текст называет переменную. ARCHEPELAG_SERVER_URL — полный адрес с https://, без логина, query и #. |
Не задан токен агента / ARCHEPELAG_AGENT_TOKEN_FILE: не удалось прочитать | Нет файла токена или у процесса агента нет прав на чтение. В режиме shell файл читает uid 10000. |
Токен агента имеет неверный формат | В файле не токен sa_… из UI (лишние символы, другой токен). |
unauthorized в журнале, агент не онлайн | Токен перевыпущен или агент удалён. Запишите новый токен в файл и пересоздайте агента (docker compose up -d --force-recreate scan-agent, в Kubernetes — kubectl rollout restart): токен агент читает только при старте. Подробнее — Перевыпуск токена. |
Агент не стартует: не удалось скачать образ …scan-agent-toolbox…, denied | Агент качает образы своим docker CLI и docker login хоста не видит. На хосте: docker login <registry>, docker compose pull, docker compose up -d. ARCHEPELAG_AGENT_PULL_POLICY оставьте if-not-present. |
ErrImagePull, ImagePullBackOff (Kubernetes) | Нет Secret archepelag-registry с логином registry образов или в нём не тот registry. См. Kubernetes. |
429 в журнале агента | Лимит edge nginx на /agent-api/: 20 запросов в секунду на токен и 200 на IP. Агент повторит запрос сам. Если это постоянно: лимит на токен агента общий для всех его экземпляров, а лимит на IP — для всех клиентов за балансировщиком без set_real_ip_from (см. ENV.md сервера, раздел агентов сканирования). |
agent_disabled | Агент отключён администратором. Текущие задания он доработает, новые не берёт. |
insecure_transport | Агент пришёл не по HTTPS. Нужен PUBLIC_URL=https://…. На стенде без TLS — AGENT_API_ALLOW_PLAINTEXT=true на сервере и ARCHEPELAG_AGENT_ALLOW_PLAINTEXT=true у агента. Если TLS снимает балансировщик перед edge, edge видит HTTP — тогда тоже нужен AGENT_API_ALLOW_PLAINTEXT=true, при условии что канал от балансировщика до edge защищён. |
unable to verify the first certificate, self-signed certificate | Агент не доверяет сертификату Archepelag. Задайте ARCHEPELAG_SERVER_CA_FILE и указывайте в адресе имя из сертификата, а не IP. |
protocol_mismatch | Версия агента не поддерживается сервером. Обновите агента до версии сервера. Агенты протокола 1 (из комплектов до встроенного хранилища) новый сервер не принимает. |
| Экземпляр помечен как устаревший | Агент работает, но его протокол сервер скоро перестанет поддерживать. Обновите агента. |
Задание завершилось ошибкой сразу
Когда агент забирает задание, Archepelag собирает для него секреты, реестры и доступ к VCS. Если чего-то нет, задание сразу завершается ошибкой с понятной причиной, а агент берёт следующее:
секрет NAME не найден (Настройки → Секреты)— создайте секрет или поправьте шаблон;файл конфигурации «…» не найден— то же для файлов конфигурации;реестр «…» не найден или выключен (Интеграции → Nexus)— имя вregistry:должно совпадать с именем подключения Nexus;интеграция … не настроена или выключена,в интеграции … не задан токен— дляcredentials: [{ integration: … }];подключение … выключено,токен подключения … не расшифровывается— проверьте подключение Bitbucket/GitHub, к которому привязан репозиторий;Хранилище результатов не настроено или выключено— своё S3, выбранное при создании запуска, выключили или удалили.
Агент перестал отвечать (lease_lost)
Задание закреплено за попыткой агента на время аренды (по умолчанию 300 секунд). Любое событие от агента её продлевает. Если агент замолчал (упал, потерял сеть, хост перегружен), задание возвращается в очередь со следующей попыткой. В истории попыток будет «Агент «…» перестал отвечать во время шага …».
- Задание завершается ошибкой, когда потерь связи становится столько, сколько разрешено попыток.
- Старая попытка, если её процесс жив, получает
409 lease_lostи останавливает свои шаги. Её результаты уже не принимаются: токен попытки отозван. - Экземпляр, который не присылает heartbeat 90 секунд, считается пропавшим, и его задания тоже возвращаются в очередь.
- Экземпляр на связи, но перестал называть начатое задание в heartbeat (процесс агента перезапустился, например из-за нехватки памяти) — это тоже потеря попытки. Поэтому задание, которое раз за разом роняет агента, завершается ошибкой, а не крутится в очереди бесконечно. Если ответ агенту на выдачу задания потерялся и задание ещё не начиналось, попытка не тратится.
- Пока API или база данных Archepelag недоступны (например, при обновлении), аренды не истекают: агенты не виноваты, что не могут достучаться. После восстановления агентам даётся время продлить аренду.
Остановка агента (docker compose down, обновление, SIGTERM) — не потеря связи: агент сам возвращает задание в очередь, попытка не тратится. Если одно задание вернули больше трёх раз, оно завершается ошибкой.
Часто теряется связь на долгих шагах — проверьте сеть от агента до Archepelag, прокси и балансировщики с коротким таймаутом. Аренду можно увеличить переменной SCAN_AGENT_LEASE_SECONDS на сервере (60–3600).
Шаг упал
| Ошибка шага | Что делать |
|---|---|
код выхода N | Смотрите лог шага. Для сканеров, которые возвращают ненулевой код при находках, добавьте флаг вроде --exit-code 0 или allowFailure: true. |
нехватка памяти (лимит 4g) | Увеличьте resources.memory шага или ARCHEPELAG_AGENT_DEFAULT_MEMORY. Для JVM также ограничьте heap (-Xmx). |
превышено время шага (…), превышено время задания (…) | Увеличьте timeoutMinutes шага или пайплайна. |
нет отчёта … | Шаг завершился успешно, но не положил объявленный отчёт в $ARCHEPELAG_OUTPUT. Проверьте путь и имя файла. Если отчёт может не появиться — optional: true. |
не удалось скачать образ … | Нет доступа к registry или образа там нет. Агент не видит docker login скан-хоста: для закрытого registry задайте registry: из Интеграции → Nexus или скачайте образ на хосте заранее (docker pull, при ARCHEPELAG_AGENT_PULL_POLICY=if-not-present). denied на ghcr.io — токен без read:packages. |
команда не найдена или не запускается в образе … | В образе нет этой программы или у образа свой ENTRYPOINT. Проверьте command[0] или используйте entrypoint: image. |
шаг требует docker-исполнитель (…) | Шаблон с полями только для docker попал на агента shell. Поставьте agent.executor: docker. |
Шаг skipped | Нет файлов по when.exists, или упал предыдущий шаг без allowFailure. |
PKIX, TLS и прокси в сборках
Сборки ходят за зависимостями. В корпоративной сети это частая причина ошибок.
PKIX path building failed(Maven, Gradle). Java не доверяет сертификату вашего Nexus или прокси с инспекцией TLS. Задайте агентуARCHEPELAG_AGENT_CA_FILEи импортируйте$ARCHEPELAG_CA_FILEв truststore в шаге (см. Свой CA для Java) или соберите образ шага с вашим CA.UNABLE_TO_GET_ISSUER_CERT_LOCALLY,self signed certificate in certificate chain(npm, Node). То же:ARCHEPELAG_AGENT_CA_FILEдаёт шагамNODE_EXTRA_CA_CERTS.Connect timed out,Could not transfer artifact(Maven). Maven не читаетHTTPS_PROXY. Задайте прокси или зеркало Nexus вsettings.xmlи подключите его к шагу как файл конфигурации.- Нет сети вообще. У шага
network: none, или docker-сетьarchepelag-stepsне выпускает наружу. Сканерам без загрузок баз сеть не нужна; сборкам и Trivy/Grype — нужна (или зеркала).
SBOM не построен
На вкладке Файлы нет SBOM, или сводка задания показывает SBOM «частично»:
- Шаг пропущен. В логе: «Шаг пропущен: нет файлов по шаблону pom.xml». Встроенные шаблоны ищут
pom.xml,build.gradle*,package.jsonтолько в корне репозитория. Для проектов в подкаталоге укажитеwhen: { exists: "**/pom.xml" }иdir:или используйте cdxgen. - Сборка упала. Смотрите лог шага: чаще всего это зависимости (см. PKIX, TLS и прокси) или нужная версия JDK (параметр
JDKу шаблона Maven). - Файл не там. Шаг должен скопировать SBOM в
$ARCHEPELAG_OUTPUTпод именем изreports. У многомодульного MavenmakeAggregateBomпишетtarget/bom.jsonв корне, у Gradle —build/reports/bom.json. - Нет
sbom: true. Без этого флага файл считается обычным отчётом и не показывается как SBOM. - SBOM «частично». Часть SBOM-шагов не завершилась успешно, или их файл записан шагом, который потом упал. Такой SBOM может быть неполным.
- Файлы удалены по сроку хранения. Перезапустите сканирование.
Файлы не загрузились
Ошибки загрузки перечислены на вкладке Файлы:
| Ошибка | Что делать |
|---|---|
размер … больше лимита … | Увеличьте Файл, МБ в настройках хранилища или уменьшите отчёт. |
превышен общий лимит объёма …, превышен лимит числа файлов | Увеличьте Задание, МБ или сократите artifacts шаблона. Отчёты из reports загружаются первыми. |
сервер не выдал ссылку для загрузки | Archepelag не смог выдать ссылку: хранилище выключено или недоступно (storage_unavailable). Проверьте его в Настройки → Интеграции → S3-хранилище. |
ссылка для загрузки истекла, недействительная ссылка для загрузки, ссылка выдана другой попытке задания (встроенное хранилище) | Разрешение на загрузку действует 15 минут и только для своей попытки. Агент один раз запрашивает разрешение заново сам. Повторяется — смотрите журнал агента: между выдачей разрешения и началом загрузки прошло больше 15 минут. «Другой попытке» значит, что задание уже отдано другому экземпляру. |
файл не совпадает с заявленным (размер или sha256) (встроенное хранилище) | Файл изменился после того, как агент его посчитал, или тело оборвалось. Archepelag удалил принятый файл. |
хранилище результатов недоступно — повторите позже (встроенное хранилище) | Archepelag не смог записать файл в S3 комплекта. Проверьте FILES_S3_* и сервис seaweedfs (или ваше S3) на сервере. |
| Ошибка соединения с S3 | Агенту недоступен Адрес для агентов хранилища. Проверьте сеть, прокси (NO_PROXY) и CA. |
unable to verify the first certificate, self-signed certificate при загрузке в S3 | Если в карточке хранилища загружен CA, агент доверяет при загрузке только ему, без системных CA. CA должен подходить к адресу для агентов: если там сертификат другого CA (в том числе публичного), загрузите в карточку PEM с CA обоих адресов — файл может содержать несколько сертификатов. |
SignatureDoesNotMatch, 403 от S3 | Прокси или балансировщик перед S3 меняет заголовок Host, или адрес для агентов не совпадает с тем, по которому агент приходит в S3. |
Находки не появились
- Вкладка Находки открывается после разбора отчётов: core-worker скачивает отчёты из S3 после завершения задания.
- «Не удалось обработать результаты: …» — разбор не удался после трёх попыток. Проверьте, что core-worker видит Адрес S3 API своего хранилища или S3 комплекта (
FILES_S3_*). - Предупреждения разбора на вкладке Файлы: файл пустой или не JSON, отчёт больше 64 МБ (сохранён, но не разобран), сохранены первые 20 000 находок из отчёта или достигнут лимит 50 000 на задание.
- Формат отчёта в
reportsдолжен совпадать с тем, что пишет инструмент:semgrep --json— этоsemgrep,--sarif— этоsarif.
Разработка: агент в Docker Desktop
Исполнитель docker запускает шаги соседними контейнерами, и Docker монтирует в них пути хоста (Docker-outside-of-Docker). Если рабочий каталог смонтирован в агента по другому пути, агент не стартует:
проверка docker не пройдена: каталог … не виден контейнерам шагов по тому же путиСмонтируйте каталог по одинаковому пути (-v /var/lib/archepelag-agent:/var/lib/archepelag-agent). В Docker Desktop путь должен существовать внутри виртуальной машины Docker, а не только в Windows. ARCHEPELAG_AGENT_SKIP_DOCKER_SELFTEST=true отключает проверку — только для разработки: при разных путях шаги увидят пустой /workspace/src.