{"meta":{"title":"Troubleshooting workflows","intro":"You can use the tools in GitHub Actions to debug your workflows.","product":"GitHub Actions","breadcrumbs":[{"href":"/en/actions","title":"GitHub Actions"},{"href":"/en/actions/how-tos","title":"How-tos"},{"href":"/en/actions/how-tos/troubleshoot-workflows","title":"Troubleshoot workflows"}],"documentType":"article"},"body":"# Troubleshooting workflows\n\nYou can use the tools in GitHub Actions to debug your workflows.\n\n## Initial troubleshooting suggestions\n\nThere are several ways you can troubleshoot failed workflow runs.\n\n> \\[!NOTE] If you are on a GitHub Copilot Free subscription, this will count towards your monthly chat message limit.\n\n### Using GitHub Copilot\n\nTo open a chat with GitHub Copilot about a failed workflow run, you can either:\n\n* Next to the failed check in the merge box, click ****, then click ** Explain error**.\n* In the merge box, click on the failed check. At the top of the workflow run summary page, click ** Explain error**.\n\nThis opens a chat window with GitHub Copilot, where it will provide instructions to resolve the issue.\n\n### Using workflow run logs\n\nEach workflow run generates activity logs that you can view, search, and download. For more information, see [Using workflow run logs](/en/actions/how-tos/monitor-workflows/use-workflow-run-logs).\n\n### Enabling debug logging\n\nIf the workflow logs do not provide enough detail to diagnose why a workflow, job, or step is not working as expected, you can enable additional debug logging. For more information, see [Enabling debug logging](/en/actions/how-tos/monitor-workflows/enable-debug-logging).\n\nIf your workflow uses specific tools or actions, enabling their debug or verbose logging options can help generate more detailed output for troubleshooting.\nFor example, you can use `npm install --verbose` for npm or `GIT_TRACE=1 GIT_CURL_VERBOSE=1 git ...` for git.\n\n## Reviewing billing errors\n\nActions usage includes runner minutes and storage for [workflow artifacts](/en/actions/tutorials/store-and-share-data). For more information, see [GitHub Actions billing](/en/billing/concepts/product-billing/github-actions).\n\n### Setting a budget\n\nSetting an Actions budget may help immediately unblock workflows failing due to billing or storage errors. It will allow further minutes and storage usage to be billed up to the set budget amount. To learn more, see [Setting up budgets to control spending on metered products](/en/billing/how-tos/set-up-budgets).\n\n## Reviewing GitHub Actions activity with metrics\n\nTo analyze the efficiency and reliability of your workflows using metrics, see [Viewing GitHub Actions metrics](/en/actions/how-tos/administer/view-metrics).\n\n## Troubleshooting workflow triggers\n\nFirst, make sure that your workflow wasn't disabled manually, see [Disabling and enabling a workflow](/en/actions/how-tos/manage-workflow-runs/disable-and-enable-workflows). A disabled workflow does not respond to its triggers.\n\nYou can review your workflow's `on:` field to understand what is expected to trigger the workflow. For more information, see [Triggering a workflow](/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow).\n\nFor a full list of available events, see [Events that trigger workflows](/en/actions/reference/workflows-and-actions/events-that-trigger-workflows).\n\n### Triggering event conditions\n\nSome triggering events only run from the default branch (i.e. `issues`, `schedule`). Workflow file versions that exist outside of the default branch will not trigger on these events.\n\nWorkflows will not run on `pull_request` activity if the pull request has a merge conflict.\n\nWorkflows that would otherwise be triggered on `push` or `pull_request` activity will be skipped if the commit message contains a skip annotation. For more information, see [Skipping workflow runs](/en/actions/how-tos/manage-workflow-runs/skip-workflow-runs).\n\n### Scheduled workflows running at unexpected times\n\nScheduled events can be delayed during periods of high loads of GitHub Actions workflow runs.\n\nHigh load times include the start of every hour. If the load is sufficiently high enough, some queued jobs may be dropped. To decrease the chance of delay, schedule your workflow to run at a different time of the hour. For more information, see [Events that trigger workflows](/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule).\n\n### Filtering and diff limits\n\nSpecific events allow for filtering by branch, tag, and/or paths you can customize. Workflow run creation will be skipped if the filter conditions apply to filter out the workflow.\n\nYou can use special characters with filters. For more information, see [Workflow syntax for GitHub Actions](/en/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet).\n\nFor path filtering, evaluating diffs is limited to the first 300 files. If there are files changed that are not matched in the first 300 files returned by the filter, the workflow will not be run. For more information, see [Workflow syntax for GitHub Actions](/en/actions/reference/workflows-and-actions/workflow-syntax#git-diff-comparisons).\n\n## Troubleshoot workflow execution\n\nWorkflow execution involves any issues seen after the workflow was triggered and a workflow run has been created.\n\n### Debugging job conditions\n\nIf a job was skipped unexpectedly, or ran when you expected it to be skipped, you can view the expression evaluation to understand why:\n\n1. Click on the job in the workflow run.\n2. Download the log archive from the job's menu.\n3. Open the `JOB-NAME/system.txt` file.\n4. Look for the `Evaluating`, `Expanded`, and `Result` lines.\n\nThe `Expanded` line shows the actual runtime values that were substituted into your `if` condition, making it clear why the expression evaluated to `true` or `false`.\n\nFor more information, see [Viewing job condition expression logs](/en/actions/how-tos/monitor-workflows/view-job-condition-logs).\n\n### Canceling Workflows\n\nIf standard cancellation through the [UI](/en/actions/reference/workflows-and-actions/workflow-cancellation) or [API](/en/rest/actions/workflow-runs?apiVersion=2022-11-28#cancel-a-workflow-run) does not process as expected, there may be a conditional statement configured for your running workflow job(s) that causes it to not cancel.\n\nIn these cases, you can leverage the API to force cancel the run. For more information, see [REST API endpoints for workflow runs](/en/rest/actions/workflow-runs?apiVersion=2022-11-28#force-cancel-a-workflow-run).\n\nA common cause can be using the `always()` [status check function](/en/actions/reference/workflows-and-actions/expressions#status-check-functions) which returns `true`, even on cancellation. An alternative is to use the inverse of the `cancelled()` function, `${{ !cancelled() }}`.\n\nFor more information, see [Using conditions to control job execution](/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-jobs-with-conditions) and [Canceling a workflow run](/en/actions/how-tos/manage-workflow-runs/cancel-a-workflow-run).\n\n## Troubleshooting runners\n\n### Defining runner labels\n\nGitHub-hosted runners leverage [preset labels](/en/actions/reference/runners/github-hosted-runners#standard-github-hosted-runners-for-public-repositories) maintained through the [`actions/runner-images`](https://github.com/actions/runner-images?tab=readme-ov-file#available-images) repository.\n\nWe recommend using unique label names for larger and self-hosted runners. If a label matches to any of the existing preset labels, there can be runner assignment issues where there is no guarantee on which matching runner option the job will run on.\n\n### Self-hosted runners\n\nIf you use self-hosted runners, you can view their activity and diagnose common issues.\n\nFor more information, see [Monitoring and troubleshooting self-hosted runners](/en/actions/how-tos/manage-runners/self-hosted-runners/monitor-and-troubleshoot).\n\n### Runner IP addresses flagged by security scanners\n\nGitHub-hosted runners use dynamically assigned IP addresses from shared infrastructure. These IP addresses are published via the Meta API (for example, the `actions` and `actions_macos` keys). For more information, see [REST API endpoints for meta data](/en/rest/meta/meta#get-github-meta-information).\n\nThird-party threat intelligence services, IP reputation scanners, or firewall vendors may flag these IP addresses as \"malicious\" or \"suspicious.\" Because the underlying infrastructure is shared, activity from other users of the same infrastructure can influence the reputation scores assigned to these addresses.\n\nGitHub does not control third-party IP reputation lists and cannot comment on their accuracy or update frequency. To verify whether an IP address belongs to GitHub-hosted runners, check the IP ranges returned by the Meta API.\n\nIf you have a security concern about a Microsoft-owned IP address, report it to the [Microsoft Security Response Center (MSRC)](https://msrc.microsoft.com/report/).\n\n## Networking troubleshooting suggestions\n\nOur support is limited for network issues that involve:\n\n* Your networks\n* External networks\n* Third-party systems\n* General internet connectivity\n\nTo view GitHub's realtime platform status, check [GitHub Status](https://githubstatus.com/).\n\nFor other network-related issues, review your organization's network settings and verify the status of any third-party services you're accessing. If problems persist, consider reaching out to your network administrators for further assistance.\n\nIf you're unsure about the issue, contact GitHub Support. For details on how to contact support, see [Contacting GitHub Support](/en/support/contacting-github-support).\n\n### DNS\n\nIssues may occur from Domain Name System (DNS) configuration, resolution, or resolver problems. We recommend you review available logs, vendor documentation, or consult with your administrators for additional assistance.\n\n### Firewalls\n\nActivities may become blocked by firewalls. If this occurs, you may want to review available logs, vendor documentation, or consult with your administrators for additional assistance.\n\n### Proxies\n\nActivities could fail when using a proxy for communications. It's good practice to review available logs, vendor documentation, or consult with your administrators for additional assistance.\n\nRefer to [Using proxy servers with a runner](/en/actions/how-tos/manage-runners/use-proxy-servers) for information about configuring the runner application to utilize a proxy.\n\n### Subnets\n\nIt is possible to encounter issues with subnets in use or overlaps with an existing network, such as within virtual cloud provider or Docker networks. In such cases, we recommend you review your network topology and subnets in use.\n\n### Certificates\n\nIssues may occur from self-signed or custom certificate chains and certificate stores. You can check that a certificate in use has not expired and is currently trusted. Certificates may be inspected with `curl` or similar tools. You can also review available logs, vendor documentation, or consult with your administrators for additional assistance.\n\n### IP lists\n\nIP allow or deny lists may disrupt expected communications. If there is a problem, you should review available logs, vendor documentation, or consult with your administrators for additional assistance.\n\nFor information on GitHub's IP addresses, such as those used by GitHub-hosted runners, see [About GitHub's IP addresses](/en/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses).\n\nStatic IP addresses are available for use with GitHub-hosted larger runners. See [Managing larger runners](/en/actions/how-tos/manage-runners/larger-runners/manage-larger-runners) for more information.\n\n### Operating systems and software applications\n\nIn addition to firewalls or proxies, customizations performed to GitHub-hosted runners, such as installing additional software packages, may result in communication disruptions. For information about available customization options, see [Customizing GitHub-hosted runners](/en/actions/how-tos/manage-runners/github-hosted-runners/customize-runners).\n\n* For self-hosted runners, learn more about necessary endpoints in [Self-hosted runners reference](/en/actions/reference/runners/self-hosted-runners).\n\n* For help configuring WireGuard, see [Using WireGuard to create a network overlay](/en/actions/how-tos/manage-runners/github-hosted-runners/connect-to-a-private-network/connect-with-wireguard).\n\n* For details about configuring OpenID Connect (OIDC), see [Using an API gateway with OIDC](/en/actions/how-tos/manage-runners/github-hosted-runners/connect-to-a-private-network/connect-with-oidc).\n\n### Azure private networking for GitHub-hosted runners\n\nIssues may arise from the use of GitHub-hosted runners within your configured Azure Virtual Networks (VNETs) settings.\n\nFor troubleshooting advice, see [Troubleshooting Azure private network configurations for GitHub-hosted runners in your organization](/en/organizations/managing-organization-settings/troubleshooting-azure-private-network-configurations-for-github-hosted-runners-in-your-organization) or [Troubleshooting Azure private network configurations for GitHub-hosted runners in your enterprise](/en/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/troubleshooting-azure-private-network-configurations-for-github-hosted-runners-in-your-enterprise) in the GitHub Enterprise Cloud docs."}