{% data reusables.actions.enterprise-github-hosted-runners %}

There are several ways you can troubleshoot failed workflow runs.

{% ifversion copilot %}

[!NOTE] If you are on a {% data variables.copilot.copilot_free %} subscription, this will count towards your monthly chat message limit.

To open a chat with {% data variables.product.prodname_copilot %} about a failed workflow run, you can either:

• Next to the failed check in the merge box, click {% octicon "kebab-horizontal" aria-hidden="true" aria-label="kebab-horizontal" %}, then click {% octicon "copilot" aria-hidden="true" aria-label="copilot" %} Explain error.
• In the merge box, click on the failed check. At the top of the workflow run summary page, click {% octicon "copilot" aria-hidden="true" aria-label="copilot" %} Explain error.

This opens a chat window with {% data variables.product.prodname_copilot %}, where it will provide instructions to resolve the issue.

{% endif %}

Each workflow run generates activity logs that you can view, search, and download. For more information, see AUTOTITLE.

If 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 AUTOTITLE.

If your workflow uses specific tools or actions, enabling their debug or verbose logging options can help generate more detailed output for troubleshooting. For example, you can use npm install --verbose for npm or GIT_TRACE=1 GIT_CURL_VERBOSE=1 git ... for git.

{% ifversion fpt or ghec %}

Actions usage includes runner minutes and storage for workflow artifacts. For more information, see AUTOTITLE.

Setting 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 AUTOTITLE.

{% endif %}

{% ifversion actions-metrics %}

To analyze the efficiency and reliability of your workflows using metrics, see AUTOTITLE. {% endif %}

You can review your workflow's on: field to understand what is expected to trigger the workflow. For more information, see AUTOTITLE.

For a full list of available events, see AUTOTITLE.

Some 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.

Workflows will not run on pull_request activity if the pull request has a merge conflict.

Workflows 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 AUTOTITLE.

Scheduled events can be delayed during periods of high loads of {% data variables.product.prodname_actions %} workflow runs.

High 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 AUTOTITLE.

Specific 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.

You can use special characters with filters. For more information, see AUTOTITLE.

For 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 AUTOTITLE.

Workflow execution involves any issues seen after the workflow was triggered and a workflow run has been created.

{% ifversion fpt or ghec %}

If a job was skipped unexpectedly, or ran when you expected it to be skipped, you can view the expression evaluation to understand why:

1. Click on the job in the workflow run.
2. Download the log archive from the job's menu.
3. Open the JOB-NAME/system.txt file.
4. Look for the Evaluating, Expanded, and Result lines.

The 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.

For more information, see AUTOTITLE.

{% endif %}

If standard cancellation through the UI or API does not process as expected, there may be a conditional statement configured for your running workflow job(s) that causes it to not cancel.

In these cases, you can leverage the API to force cancel the run. For more information, see AUTOTITLE.

A common cause can be using the always() status check function which returns true, even on cancellation. An alternative is to use the inverse of the cancelled() function, {% raw %}${{ !cancelled() }}{% endraw %}.

For more information, see AUTOTITLE and AUTOTITLE.

{% data variables.product.github %}-hosted runners leverage preset labels maintained through the actions/runner-images repository.

We 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.

If you use self-hosted runners, you can view their activity and diagnose common issues.

For more information, see AUTOTITLE.

Our support is limited for network issues that involve:

• Your networks
• External networks
• Third-party systems
• General internet connectivity

To view {% data variables.product.github %}'s realtime platform status, check {% data variables.product.github %} Status.

For 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.

If you're unsure about the issue, contact {% data variables.contact.github_support %}. For details on how to contact support, see AUTOTITLE.

Issues 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.

Activities 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.

Activities 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.

Refer to AUTOTITLE for information about configuring the runner application to utilize a proxy.

It 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.

Issues 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.

IP 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.

{% ifversion ghec %} If your {% data variables.product.github %} account is configured with an IP allowlist, workflows will fail if a runner uses an IP address that isn’t included in the allowlist. To resolve this, verify that the runner's IP addresses are added to your organization's or enterprise's allowlist. For more details, see AUTOTITLE and/or AUTOTITLE. {% endif %}

{% ifversion fpt or ghec %} For information on {% data variables.product.github %}'s IP addresses, such as those used by {% data variables.product.github %}-hosted runners, see AUTOTITLE.

Static IP addresses are available for use with {% data variables.product.github %}-hosted larger runners. See AUTOTITLE for more information. {% endif %}

In addition to firewalls or proxies, customizations performed to {% data variables.product.github %}-hosted runners, such as installing additional software packages, may result in communication disruptions. For information about available customization options, see AUTOTITLE.

• For self-hosted runners, learn more about necessary endpoints in AUTOTITLE.

• For help configuring WireGuard, see AUTOTITLE.

• For details about configuring OpenID Connect (OIDC), see AUTOTITLE. {% ifversion fpt or ghec %}

Issues may arise from the use of {% data variables.product.github %}-hosted runners within your configured Azure Virtual Networks (VNETs) settings.

For troubleshooting advice, see AUTOTITLE or {% ifversion ghec %}AUTOTITLE{% else %}AUTOTITLE in the {% data variables.product.prodname_ghe_cloud %} docs{% endif %}.

{% endif %}