Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A GitHub Actions job hangs for hours: set a timeout

ErrorA run stays In progress for hours with no new log output

Short answer

Without a setting, a job runs until it finishes or reaches 360 minutes, and a hung step uses all of that time. Set timeout-minutes on the job, and on any step that tends to hang. There is no single workflow-level key; the value goes on each job.

  • Applies to GitHub Actions
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check which jobs and steps already carry a timeout. Anything without one can run for the default six hours.

    grep -n "timeout-minutes" .github/workflows/*.yml
  2. 2Match what you see, then jump to its fix

    1. 1A hung run is only cancelled after 360 minutes.The job has no timeout-minutes, so the default of 360 appliesFix
    2. 2The log stops inside one step, such as a network call or an interactive prompt.One step hangs, while the rest of the job is fineFix
    3. 3The job is cancelled earlier than the timeout-minutes you set.A limit longer than the runner allowsFix

What does the error look like?

  • A run stays In progress for hours with no new log output
  • The run is cancelled after 360 minutes

Cause 1 of 3

The job has no timeout-minutes, so the default of 360 applies

1Check

timeout-minutes is the maximum number of minutes GitHub lets a job run before cancelling it. The default is 360.

grep -n -B3 "runs-on" .github/workflows/*.yml

2Fix

Set a limit a little above the longest healthy run of that job.

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 20

3Verify

Break the job on purpose with a sleep longer than the limit: it is cancelled at 20 minutes.

gh run list --limit 3

Confirmed by docs.github.com

Did this fix it?

Cause 2 of 3

One step hangs, while the rest of the job is fine

1Check

A step has its own timeout-minutes: a positive integer, with fractions not supported. When it is reached, the runner kills the step's process.

grep -n -B2 -A4 "run:" .github/workflows/*.yml

2Fix

Put a short limit on that step, so the failure is clear and fast.

steps:
  - name: Wait for service
    run: ./wait-for-service.sh
    timeout-minutes: 5

3Verify

A hung step now fails after five minutes with the job marked failed.

gh run watch --exit-status

Confirmed by docs.github.com

Did this fix it?

Cause 3 of 3

A limit longer than the runner allows

1Check

If timeout-minutes is longer than the runner's execution time limit, the job is cancelled when that limit is reached. The GITHUB_TOKEN also expires when the job finishes or after 24 hours at most.

grep -n "timeout-minutes" .github/workflows/*.yml

2Fix

Set a value inside the runner's limit, or split the work into several jobs.

jobs:
  part-one:
    timeout-minutes: 120

3Verify

The job completes or is cancelled at the value you set.

gh run list --limit 3

Confirmed by docs.github.com

Did this fix it?

How do I stop it coming back?

  • Set timeout-minutes on every job as part of the workflow template you copy.
  • Choose the value from your longest healthy run, not from the 360 default.
  • Put a step-level timeout on network waits and anything that can prompt for input.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Servers

docker pull or push to ghcr.io fails with 'denied'

Error response from daemon: denied

ghcr.io refuses a pull or push when Docker is not logged in, when the token lacks the package scope, or when the workflow's GITHUB_TOKEN has no packages permission or no access to that package.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.