---
title: Run logs
description: Job logs inside Pipedash. Covers the Logs tab, steps and groups, search, error navigation, copy, download, the iPhone log screen and the log cache.
---

The Run details dialog has a Logs tab for providers that declare the `logs` capability. GitHub Actions is the only one today. The tab lists the jobs of the run and shows the log of one job, so a failure can be read without opening the provider's site. Other providers keep the dialog without tabs and a button that opens the provider's log page.

Pipedash downloads each job log once, splits it into lines, steps and groups, and keeps it on disk. The dialog then asks for the lines on screen and for search results only. Logs of several hundred MB stay fast on the desktop app, the web server and the iPhone app.

## Logs tab

<Screenshot src="run-logs" alt="Logs tab of a failed GitHub run with the jobs lint, test and build, and the failed test step open at its error line" caption="A failed run opens on its failed job, with the failed step open at the error." />

A click on a row of the [run history](/docs/features/run-history) opens the Run details dialog on the Logs tab. The Details tab holds the run fields. The dialog footer has an "Open in GitHub Actions" button.

The tab opens the first failed job. Without a failed job, it opens the first job with a log. Each job row shows a status icon, the job name and the duration.

- **Wide window:** the jobs sit in a list at the left of the log. The selected job is highlighted.
- **Window of 768 px and below:** a select field labeled "Job" sits above the log, with the jobs grouped by stage.

The tab shows "Loading jobs…" while it reads the job list. A failure shows "Couldn't load jobs" with a Retry button. A run without jobs shows "This run has no jobs yet". While the run is active, the job list refreshes every 10 seconds.

## Job states

| State | What the tab shows |
|---|---|
| Downloading | "Downloading log…" with the size received so far, or "Preparing log…" before the first bytes. |
| Waiting for the job | "Logs appear when this job finishes", the steps of the job with their status and duration, and an "Open job in GitHub Actions" button. |
| Ready | The log. |
| Empty | "This job didn't write any output". |
| Failed | "Couldn't load the job log" with the reason, a Retry button and an "Open job in GitHub Actions" button. |

The tab updates on its own when a download finishes or a waiting job ends, without a new selection. After a failed download, Pipedash waits 5 minutes before it downloads the log again. The Retry button tries at once.

GitHub serves a job log only after the job ends, so a running job shows the waiting state. GitHub also deletes logs after its retention period. An expired log fails with "The provider no longer has this log. It may have expired."

## Steps and groups

The log is split into collapsible sections.

- **Steps:** each step of the job is a section with a header. The header shows the status icon, the step name, the number of errors and the duration. Pipedash places steps with the step markers of the log, such as `##[group]Run make` on GitHub, and falls back to the step start times.
- **Groups:** `##[group]` and `##[endgroup]` markers become nested sections inside a step. The arrow on the group line opens or closes it.

A failed step opens on its own, and so does the only step of a job. A group with errors opens on its own. The others start closed. When the header of a step scrolls out of view, it stays pinned at the top of the log. A click on the pinned header returns to it.

The log opens on the first error of the failed step. A log without errors opens at the top.

## Lines

Each line shows its number. Error lines have a red background and an error icon. Warning lines have an orange background and a warning icon. Command lines are blue and debug lines are dimmed. ANSI colors map to the colors of the theme. Links in the text open in the browser.

A line longer than 4096 characters ends with a button such as "… 120 more characters". It opens the full line in a dialog with a copy button.

The Log options menu holds two display switches. Pipedash saves both.

- **Wrap lines:** on by default. When off, long lines scroll sideways and the line numbers stay in place.
- **Show timestamps:** off by default. When on, each line shows its time as `HH:mm:ss.SSS` in local time.

A log above 1 GB of text stops at that size. A banner says "Showing the first 1 GB of this log. Open the job in GitHub Actions for the rest."

## Search

The search field has the placeholder "Search logs" and accepts up to 1000 characters. Pipedash searches the whole log, not only the loaded lines.

<Screenshot src="run-logs-search" alt="Logs tab with the search useRunQueries, the counter 1 of 2 and both matches highlighted" caption="Matches are highlighted in the log and marked on the overview bar at the right." />

| Control | Effect |
|---|---|
| "Match case" | Makes the search case sensitive. |
| "Use regular expression" | Reads the text as a regular expression. An invalid one shows "Invalid search pattern". |
| Counter | Shows the current match, such as `3 of 12`. A `+` follows the total when the search stopped at 10,000 matches. "No results" when nothing matches. |
| "Previous match", "Next match" | Moves between matches and opens closed sections on the way. |
| "Show matching lines only" | Hides every line without a match. A click on a line clears the filter and shows the line in its place. |

Enter goes to the next match and Shift+Enter to the previous one. Escape clears the search. Clearing the search also turns off "Show matching lines only".

## Error navigation

The toolbar shows the number of error lines with previous and next buttons. The buttons are disabled with the tooltip "No error lines found" when the log has no errors. "Show error lines only" in the Log options menu hides the other lines.

At the right of the log, a thin overview bar marks errors in red, warnings in orange and search matches in blue. A band shows the visible part. Dragging the bar scrolls the log. With keyboard focus on the bar, the arrow keys move by 1% of the log and Page Up and Page Down by 10%. The bar is hidden on the iPhone.

Navigation covers the first 10,000 error lines of a log. The counts in the toolbar and in the step headers stay exact beyond that.

## Keyboard shortcuts

These shortcuts work while the Logs tab is open. `Mod` is Cmd on macOS and Ctrl elsewhere.

| Shortcut | Effect |
|---|---|
| `Mod+F` | Focuses the search field |
| `Mod+G`, `Shift+Mod+G` | Next and previous match |
| `F8`, `Shift+F8` | Next and previous error |
| `Mod+Home`, `Mod+End` | First and last line |

Tab reaches the line number buttons of the log. The arrow and Page keys then scroll the log.

## Copy

A click on a line number selects the line. Shift+click extends the selection. `Mod+C` or the "Copy N lines" button copies the selection. A right-click on a line opens a menu with Copy line, Copy step output and, for a long line, Show full line.

Copies hold the full text of each line. A copy stops at 50,000 lines or about 4 million characters. A larger selection shows "The selection is too large to copy. Download the log instead."

## Download

"Download log" in the Log options menu saves the job log as a text file. The file name has the form `<workflow>-run-<N>-<job>.log`. The file holds the text Pipedash shows, with the original timestamps and without ANSI codes and group markers.

- **Desktop app:** a save dialog asks for the destination.
- **Web:** the browser downloads the file through a single-use link that expires after 60 seconds. The link carries no API token. With more than 32 pending downloads, the server answers "Too many downloads are pending. Try again in a minute."
- **iPhone:** the system document picker opens. The [mobile page](/docs/deployment/mobile) covers exports.

A download that stops early, for example because Pipedash closed, ends with an error instead of a short file. A failure shows "Couldn't export the log".

## iPhone

The run sheet lists the jobs below the run fields, in one group per stage or in a single "Jobs" group. Failed jobs come first. A tap on a job opens its log in a sheet. The back button reads `#N`, the run number.

- **Search:** a search field sits at the top. The Search key on the keyboard goes to the next match, and a row shows the counter with previous and next buttons.
- **Toolbar:** the bottom toolbar has "Next error" with the error count and "Matching lines" while a search is active. "More" opens Wrap lines, Show timestamps, Show error lines only, Go to top, Go to bottom, Export log and "Open job in GitHub Actions".
- **Gestures:** the log scrolls with momentum. A tap on the status bar returns to the first line. Pulling down at the top closes the sheet.

Text in the log follows the Dynamic Type size. Copy uses the system text selection.

## Log cache

Pipedash keeps downloaded logs on disk in `<data_dir>/cache/run-logs`, compressed. A finished job log is downloaded once and read from the cache after that.

| Limit | Value |
|---|---|
| Disk budget | 2 GB on the desktop app and the web server, 512 MB on the iPhone |
| Idle time | 30 days without a read |
| Text per log | 1 GB |

When the cache passes its budget, Pipedash deletes the least recently read logs until it is back under 90% of the budget. It never deletes a log that is downloading or being read. Logs without a read for 30 days go too.

Saving a provider in Settings or removing it deletes the cached logs of that provider. While the API quota of a provider is paused, Pipedash sends it no log request. The [GitHub Actions](/docs/providers/github-actions) page covers the pause. The Settings Cache page shows the size of the log cache and clears it. The [Cache](/docs/features/cache) page covers it.