# Buildkite Troubleshooting and Debugging Documentation

> Buildkite documentation for debugging and troubleshooting builds, agents, and infrastructure, covering log output management, build annotations, terminal access, agent lifecycle, and platform-specific troubleshooting guides.

## Pipelines

### Agent

#### Self-hosted agents

##### Run on Kubernetes

- [Troubleshooting](https://buildkite.com/docs/agent/self-hosted/agent-stack-k8s/troubleshooting.md): Debugging agent-stack-k8s issues using debug mode, Kubernetes log collection, and common error solutions.

##### Run on AWS

###### Elastic CI Stack

###### EC2 Linux and Windows

- [Troubleshooting](https://buildkite.com/docs/agent/self-hosted/aws/elastic-ci-stack/ec2-linux-and-windows/troubleshooting.md): Debugging Elastic CI Stack for AWS using CloudWatch Logs, log-collector scripts, and common issue solutions.

###### EC2 Mac

- [Troubleshooting](https://buildkite.com/docs/agent/self-hosted/aws/elastic-ci-stack/ec2-mac/troubleshooting.md): Troubleshooting EC2 Mac agent issues: Auto Scaling failures, agent startup, Xcode access, and SSH connectivity.

##### Run on Google Cloud

###### Elastic CI Stack

- [Troubleshooting](https://buildkite.com/docs/agent/self-hosted/gcp/elastic-ci-stack/troubleshooting.md): Debugging Elastic CI Stack for GCP using Cloud Logging, serial console, SSH access, and common issue solutions.

#### Buildkite hosted agents

##### macOS hosted agents

- [Troubleshooting fastlane](https://buildkite.com/docs/agent/buildkite-hosted/macos/troubleshooting-fastlane.md): Troubleshooting fastlane issues on Buildkite hosted macOS agents: code signing, provisioning profiles, and keychains.
- [Terminal access](https://buildkite.com/docs/agent/buildkite-hosted/terminal-access.md): Accessing a live terminal on running hosted agent jobs for debugging and environment inspection.
- [Agent lifecycle](https://buildkite.com/docs/agent/lifecycle.md): Agent lifecycle stages, signal handling (SIGTERM/SIGQUIT), exit codes, and troubleshooting common issues.

#### Command-line reference

- [annotate](https://buildkite.com/docs/agent/cli/reference/annotate.md): CLI reference for buildkite-agent annotate: adding Markdown annotations to build pages with styles and contexts.
- [annotation](https://buildkite.com/docs/agent/cli/reference/annotation.md): CLI reference for buildkite-agent annotation: removing existing build annotations by context.

### Configure pipelines

- [Managing log output](https://buildkite.com/docs/pipelines/configure/managing-log-output.md): Formatting build log output with collapsible groups, ANSI colors, redaction, and log limits.
- [Links and images in log output](https://buildkite.com/docs/pipelines/configure/links-and-images-in-log-output.md): Embedding clickable links and inline images in build logs using ANSI escape codes.

## APIs

### REST

#### Pipelines 

- [Annotations](https://buildkite.com/docs/apis/rest-api/annotations.md): REST endpoints to list and create Markdown annotations on builds.

## See also

- [Buildkite Insights Documentation](https://buildkite.com/docs/llms-insights.txt): Buildkite documentation for pipeline and cluster insights, including waterfall views, cluster metrics, and queue monitoring.
- [Buildkite Self-Hosted Agent Documentation](https://buildkite.com/docs/llms-self-hosted-agents.txt): Buildkite documentation for self-hosted agents, covering installation on Linux, macOS, Windows, and Docker, running on AWS, GCP, and Kubernetes, agent configuration, security, monitoring, and the CLI reference.
- [Buildkite Hosted Agent Documentation](https://buildkite.com/docs/llms-hosted-agents.txt): Buildkite documentation for Buildkite hosted agents, covering Linux and macOS instances, cache volumes, internal container registry, remote Docker builders, network security, code access, pipeline migration, and terminal access.