Разделы документации

Устранение неполадок

Что делать, если агент не подключается, задание ждёт в очереди, шаг упал, 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 «частично»:

  1. Шаг пропущен. В логе: «Шаг пропущен: нет файлов по шаблону pom.xml». Встроенные шаблоны ищут pom.xml, build.gradle*, package.json только в корне репозитория. Для проектов в подкаталоге укажите when: { exists: "**/pom.xml" } и dir: или используйте cdxgen.
  2. Сборка упала. Смотрите лог шага: чаще всего это зависимости (см. PKIX, TLS и прокси) или нужная версия JDK (параметр JDK у шаблона Maven).
  3. Файл не там. Шаг должен скопировать SBOM в $ARCHEPELAG_OUTPUT под именем из reports. У многомодульного Maven makeAggregateBom пишет target/bom.json в корне, у Gradle — build/reports/bom.json.
  4. Нет sbom: true. Без этого флага файл считается обычным отчётом и не показывается как SBOM.
  5. SBOM «частично». Часть SBOM-шагов не завершилась успешно, или их файл записан шагом, который потом упал. Такой SBOM может быть неполным.
  6. Файлы удалены по сроку хранения. Перезапустите сканирование.

Файлы не загрузились

Ошибки загрузки перечислены на вкладке Файлы:

ОшибкаЧто делать
размер … больше лимита …Увеличьте Файл, МБ в настройках хранилища или уменьшите отчёт.
превышен общий лимит объёма …, превышен лимит числа файловУвеличьте Задание, МБ или сократите 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.

Связанные страницы