View a markdown version of this page

Troubleshoot failed builds with AI - Preview - EC2 Image Builder
PrerequisitesSet up troubleshootingDevOps Agent pricing for troubleshooting buildsTroubleshoot a failed buildTroubleshoot multiple failed pipelinesAsk follow-up questionsWhat Troubleshoot investigatesConsiderations

Troubleshoot failed builds with AI - Preview

Preview feature

This feature is in preview and is subject to change.

When EC2 Image Builder builds fail, the root cause can be time-consuming and complex to identify. The Troubleshoot feature in Image Builder, powered by AWS DevOps Agent, automates this process with AI-powered analysis. You can quickly identify the cause of complex build failures or detect patterns across multiple failed pipelines.

When a build fails, you can use Troubleshoot to analyze build logs, Amazon CloudWatch logs, workflow step executions, and related AWS resources. You receive a root cause analysis and remediation steps to resolve the issue.

You can troubleshoot a single failed pipeline build or analyze multiple failed pipelines to identify common patterns and shared root causes.

Prerequisites

Before you use the Troubleshoot feature, make sure that the IAM user or role that you use has the following permissions:

  • aidevops:ListAgentSpaces – Required to discover available agent spaces.

  • aidevops:CreateChat – Required to start troubleshooting sessions.

  • aidevops:SendChatMessage – Required to send messages during troubleshooting.

  • aidevops:CreateAgentSpace – Required only if you want Image Builder to create an agent space for you. You can omit this permission if you bring your own agent space.

For more information about IAM policies, see Policies and permissions in IAM.

The Create with AI feature uses the same permissions and agent space. For more information, see Create and update resources with AI - Preview.

Set up troubleshooting

The Troubleshoot feature requires an AWS DevOps Agent agent space. You can use an existing agent space or have Image Builder create one for you:

  • Bring your own agent space – If you already have an agent space, Image Builder uses it for troubleshooting.

  • Have Image Builder create one – If you don't have an agent space, Image Builder creates and configures one when you start your first investigation. This option requires the aidevops:CreateAgentSpace permission.

To start troubleshooting, choose the Troubleshooting icon in the AWS Management Console header.

Note

For more information about AWS DevOps Agent, see the AWS DevOps Agent User Guide.

DevOps Agent pricing for troubleshooting builds

The Troubleshoot feature uses AWS DevOps Agent. AWS bills DevOps Agent usage separately from Image Builder, based on the time that the agent spends working on your investigation, per agent-second. Creating an agent space is free. Charges appear in your AWS bill and in Cost Explorer under AWS DevOps Agent. For current rates, see AWS DevOps Agent pricing.

During an investigation, the agent also queries other AWS services on your behalf, such as Amazon CloudWatch Logs. Those services bill the queries at their standard rates.

Troubleshoot a failed build

When an image build fails, you can start an AI-powered investigation from several entry points in the Image Builder AWS Management Console.

Start a troubleshooting investigation

Use one of the following methods to start troubleshooting a failed build:

  • Pipelines table – Choose the Troubleshooting icon next to a failed pipeline status in the Image pipelines list.

  • Output images table – Choose the Troubleshooting icon next to a failed image build in the output images list.

  • Troubleshooting drawer – In the AWS Management Console header, choose the Troubleshooting icon, then select the pipeline you want to investigate.

During the investigation

After you start troubleshooting, Troubleshoot investigates the failure. You can track real-time progress in the drawer as logs and resources are analyzed. The investigation typically completes in a few minutes. You can continue working in other AWS Management Console areas while the analysis runs. When the investigation completes, you receive:

  • Root cause analysis that identifies why the build failed

  • Remediation steps to resolve the issue

  • Commands or configuration changes to fix the problem

After you review the results, you can ask follow-up questions about the investigation in the same conversation. For more information about follow-up questions, see Ask follow-up questions. To copy the root cause report, choose the Copy response icon. This copies the root cause report, not answers to follow-up questions. To provide feedback on the investigation, choose Helpful or Not helpful. Your rating applies to the whole investigation, including its follow-up questions. To rerun the analysis against the same failed build, choose Troubleshoot again.

Troubleshoot multiple failed pipelines

If you have multiple failed pipelines, you can analyze them together to identify common patterns and shared root causes.

Start an aggregate investigation

Use one of the following methods to troubleshoot multiple pipelines:

  • In the Image pipelines table, select multiple failed pipelines and choose Troubleshoot selected.

  • Open the troubleshooting drawer and choose Troubleshoot all to analyze all failed pipelines.

Aggregate analysis results

You receive a grouped analysis organized by root cause. For each group, you get:

  • Description of the shared root cause

  • Pipelines affected by that root cause

  • Remediation steps for the group

After the aggregate analysis, you can ask follow-up questions about the analysis, or choose a drill-down prompt to investigate a specific pipeline in more detail. For more information about follow-up questions, see Ask follow-up questions.

Ask follow-up questions

After an investigation completes, you can ask follow-up questions about the results in the same conversation. The agent keeps the context of the investigation. You can ask follow-up questions after you troubleshoot a single failed build or multiple failed pipelines, including after you drill down into a specific pipeline. For example, you can ask which step failed and why, or how to apply a remediation step. You can also ask about anything else in the report.

To ask a follow-up question

  1. After the investigation completes, enter your question in the Ask a follow-up question box at the bottom of the troubleshooting drawer.

  2. Choose Send (send icon) or press Enter. The agent's answer appears in the conversation.

  3. (Optional) To stop a response while it's in progress, choose Stop troubleshooting in the drawer header.

Follow-up questions work as follows:

  • You can enter up to 4,000 characters per question. A character count appears as you approach the limit.

  • You can send a new question after the agent finishes responding.

  • If a follow-up question fails, the drawer keeps your investigation. The drawer also restores your question in the input box, so you can send it again.

What Troubleshoot investigates

When you troubleshoot a failed build, the analysis covers the following areas:

  • Failure context – Reads the structured failure details on the failed image to scope the investigation to the stage, workflow step, component step, or destination AWS Region that failed. For more information, see Find the cause of a failed image build with failure context.

  • Build logs and Amazon CloudWatch logs – Checks for errors, non-zero exit codes, timeouts, and stack traces.

  • Workflow step executions – Identifies the failed step and examines its details.

  • Networking and permissions – Reviews IAM instance profile permissions, security groups, subnet routing, NAT gateways, internet gateways, and VPC endpoints.

  • Components and recipe configuration – Checks for script errors, missing dependencies, broken URLs, and base AMI validity.

  • Network connectivity – Checks AWS Systems Manager (Systems Manager) Agent reachability, DNS resolution, and proxy configuration.

  • Build history – Reviews recent builds to distinguish persistent failures from intermittent issues.

Considerations

Note the following when using the Troubleshoot feature:

  • Troubleshoot performs read-only analysis. Your resources are not modified.

  • Troubleshooting is scoped to Image Builder build failures and related infrastructure such as IAM, VPC, and Systems Manager Agent.

Note

AI generates these responses. Verify the analysis and recommendations before you modify your resources.

For more information about troubleshooting Image Builder pipeline builds, see Troubleshoot pipeline builds.