When no candidate or pull request appears
This page explains how to isolate the cause when a remediation plan candidate or PR does not appear.
Collecting diagnostics
- Note the target workload, image, and scan time
- Check the item's category, reason, and details in Slack, the webhook, or the saved plan
- For PR processing problems, check the notified PR status and operation results alongside the KestreLynx logs from the same run
For saved records, see Stored records; for reason code definitions, see Reason codes.
Checking for a missing plan
| Symptom | What to check | Reference |
|---|---|---|
| Startup stops while loading configuration | Check the settings identified in the logs and the combination of enablement settings. | Startup validation |
| The plan has no item for the target | Check the running-image scan results, selected severities, and fixed-version information. | Image candidate selection, Language package candidate selection |
| A plan record exists, but no notification arrives | Check notification destinations, delivery conditions, and delivery failure logs. | Notification conditions, Remediation plan redelivery |
| Source files cannot be retrieved, or a target file is missing | Check Compose labels, mappings, the base branch, paths, and GitHub access. | Source mappings, GitHub access |
| A private image cannot be accessed | Check the registry host, credentials, pull permissions, and token service permissions. | Image registry authentication |
| No new image candidate appears | Use the reason in the notification to check for newer tags, new content, and improvements. | Image candidate reasons |
| Tag listing stops before completion | Check retrieval failure logs and the limits on tag listing, registry requests, and processing time. | Tag discovery, Processing limits |
| An image is treated as locally built | Check Compose's build setting and the Dockerfile and dependency file mappings. |
Excluding local builds |
| The base image cannot be confirmed | Check the target Dockerfile stage, the base used, and the matching results against the running image. | Base layer matching, Image candidate reasons |
Checking update failures
| Symptom | What to check | Reference |
|---|---|---|
| Language packages remain candidates without being updated | Check whether PR creation is enabled and the reason attached to the item. | Enablement settings, Execution scope of plans and PRs |
| An input format or package source is reported as unsupported | Check dependency files, workspaces, additional configuration, and package sources. | Supported input formats, Source reasons |
| A runtime cannot be selected, or compatibility requirements are not met | Check declarations in version files and manifests, dependency requirements, and the support status of the release series. | Runtime selection, Runtime reasons |
| The pip verification environment cannot be determined or does not match | Check the running image's Python version, OS, and platform, and the images sharing the same dependency files. | pip verification environment |
| Processing is deferred until a tool release is old enough | Check the release time, configured waiting period, and availability time shown in the details. | Minimum tool release age, Tool retrieval reasons |
| A tool cannot be retrieved | Check connectivity to the download destination, retrieval limits, and notification details. | Tool downloads, Tool retrieval reasons |
| A tool hash does not match | Check the declared hash and the retrieval and verification details. | Tool version declarations, Tool retrieval and verification |
| The tool cache cannot be used | Check write permissions for the storage location, free space, and cache capacity settings. | Tool cache capacity, Tool retrieval reasons |
| A work container cannot run | Check the Docker API, the work image download source, and work environment validation logs. | Enabling fix pull requests, Work container execution |
| The worker program cannot be used | Check the distribution in use and the logs, and also check the worker program's location for custom builds. | Worker program location |
| Processing stops at a limit or deadline | Check the limit shown in the notification, configured values, and the next scheduled run. | Processing limits, Update result reasons |
| An update does not reach a fixed version, or only part of it appears in the PR | Check excluded packages, remaining versions, and parent packages' dependency ranges. | Partial PRs, Update result reasons |
| Checks of updated files or accompanying changes fail | Check changed files, lockfile formats, dependency ranges, and verification results against package distributions. | Validating accompanying changes, Update result reasons |
| Results cannot be compared, findings remain, or new findings appear | Check scan logs, comparison conditions, and remaining and introduced findings after the update. | Scan comparison conditions, Resolved findings in comparisons |
Checking for a missing PR
| Symptom | What to check | Reference |
|---|---|---|
| A candidate exists, but no PR appears | Check PR enablement, source mappings, and whether the target uses a supported editable format. | Enablement settings, Source mappings, Supported input formats |
| GitHub rejects a write | Check the token's target repositories and permissions, and the repository rules. | GitHub access, PR processing reasons |
| The limit on new or open PRs is reached | Check current PRs and the configured limits. | Processing limits |
| An update matches an existing PR, and no new PR is created | Check the existing PR shown in the notification and whether the same update was previously closed without merging. | Matching existing PRs, Handling closed PRs |
| Source files or candidates change during PR preparation | Check notification details and the current source and candidates, then check the next cycle's results. | PR processing reasons |
| A GitHub operation fails or has an unknown outcome | Check access, connectivity, and operation results, and wait for KestreLynx to reconcile operations with unknown outcomes. | PR operation event fields, PR processing reasons |
Checking record reconciliation failures
| Symptom | What to check | Reference |
|---|---|---|
| Plan or PR records cannot be saved | Check the persistent volume mount, storage permissions, free space, and logs. | Storage location, Storage reasons |
| Records are locked | Check whether another KestreLynx instance is running with the same storage location. | Storage reasons |
| Existing PRs cannot be reconciled with records | Check GitHub access, identification markers in PR bodies, and the change history of PRs and repositories. | Record recovery, PR processing reasons |
| Writes stop because of record corruption, format problems, or operation history issues | Check the logs and notification details to identify the cause. | Stopping writes, Storage reasons |
Preserve records
Do not delete PR records to force a retry. They are needed to prevent closed updates from being recreated and to reconcile previous operations.