# How to Report Broken or Dead Links in the Free-Programming-Books Repository > Find out how to report broken or dead links in the free-programming-books repository. Learn to submit GitHub Issues or Pull Requests to help maintain the resource. - Repository: [Free Ebook Foundation/free-programming-books](https://github.com/EbookFoundation/free-programming-books) - Tags: how-to-guide - Published: 2026-02-23 --- **To report a broken link in the Free-Programming-Books repository, open a new GitHub Issue specifying the exact URL, file location, and error type, or submit a Pull Request replacing the dead URL with a working alternative.** The **Free-Programming-Books** repository maintains a curated collection of programming resources across multiple languages and formats. Keeping these thousands of links functional requires community participation to identify and resolve dead URLs. Whether you encounter a 404 error, SSL certificate failure, or a domain that no longer resolves, the project provides structured workflows for reporting these issues efficiently. ## Opening a GitHub Issue for Dead Links According to [`docs/CONTRIBUTING.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/docs/CONTRIBUTING.md), the primary method for reporting link problems is to **open a new Issue** with your findings. The contribution guidelines explicitly instruct contributors to *"open an [Issue] with your links propositions"* when discovering problematic URLs. ### Required Information for Issue Reports When submitting an issue, include these specific details to expedite resolution: - **The exact broken URL** that returns an error or redirects to unrelated content - **The file path and line number** where the entry appears (e.g., [`books/free-programming-books-langs.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/books/free-programming-books-langs.md) at line 1199) - **A description of the error** (404 Not Found, SSL handshake failure, timeout, etc.) - **A suggested replacement** (optional but recommended), such as an archived copy from the Wayback Machine or an alternative official source ### Example Issue Template Use this markdown format when creating your issue: ```markdown **Broken link:** http://example.com/old-resource.pdf **Location:** `books/free-programming-books-langs.md` (line 1199) **Problem:** Returns HTTP 404 (page not found). **Suggested action:** - Replace with archived copy: https://web.archive.org/web/20220101010101/http://example.com/old-resource.pdf - Or remove if no archived version exists. ``` You can also pre-fill the issue form using a URL shortcut: ``` https://github.com/EbookFoundation/free-programming-books/issues/new?title=Dead+link+in+free-programming-books-langs.md&body=**Broken+link:**+http://example.com/old-resource.pdf%0A**Location:**+`books/free-programming-books-langs.md`+(line+1199)%0A**Problem:**+HTTP+404%0A%0A**Suggested+action:**+... ``` ## Submitting a Pull Request to Fix Broken Links If you have a working replacement URL, you can resolve the issue directly by submitting a **Pull Request**. This approach bypasses the issue queue and immediately updates the resource list. ### Triggering the URL Validation Workflow The repository runs an automated **URL-validation workflow** defined in [`.github/workflows/check-urls.yml`](https://github.com/EbookFoundation/free-programming-books/blob/main/.github/workflows/check-urls.yml). This workflow executes the `awesome_bot` tool on every push and pull request to verify link integrity. When you submit a PR that modifies link files, the CI automatically checks whether your replacement URLs are valid and posts a summary report. ### Commit Message Format To ensure the automated checker validates your specific changes, include the file path in your commit message using this format: ```bash git commit -m "Fix dead link in Python resources check_urls=books/free-programming-books-langs.md" ``` This triggers the workflow to run `awesome_bot` against the specified file, as configured in lines 6-11 of the workflow definition. ## Understanding the Automated URL Validation The repository employs continuous integration to catch broken links before they reach users. The [`.github/workflows/check-urls.yml`](https://github.com/EbookFoundation/free-programming-books/blob/main/.github/workflows/check-urls.yml) file defines a GitHub Actions workflow that executes on every push and PR, running `awesome_bot` to validate all URLs in the markdown files. According to the workflow configuration (lines 66-71), the tool generates a detailed report of any failures, including status codes and redirect chains. This automation helps maintainers identify patterns of dead links across multiple files without manual checking. ## Summary - **Open an Issue** when you find a broken link but do not have a replacement, including the exact URL, file location, and error type. - **Submit a Pull Request** if you can provide a working replacement URL, using the `check_urls=` prefix in your commit message to trigger validation. - **Reference specific file paths** such as [`books/free-programming-books-langs.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/books/free-programming-books-langs.md) with line numbers to help maintainers locate entries quickly. - **Trust the automated workflow** powered by `awesome_bot` to verify fixes and catch regressions in [`.github/workflows/check-urls.yml`](https://github.com/EbookFoundation/free-programming-books/blob/main/.github/workflows/check-urls.yml). ## Frequently Asked Questions ### What information do I need to include when reporting a dead link? You must provide the exact broken URL, the specific file path (e.g., [`books/free-programming-books-langs.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/books/free-programming-books-langs.md)), and the line number where the link appears. Additionally, describe the error type—whether it is a 404 error, SSL failure, or domain timeout—and optionally suggest a replacement URL or archived version. ### Can I fix a broken link myself instead of opening an issue? Yes, you can submit a Pull Request directly if you have a working replacement URL. Fork the repository, edit the relevant markdown file to update the dead link, and commit with a message containing `check_urls=` followed by the file path to trigger the automated validation workflow. ### How does the repository automatically detect broken links? The repository uses a GitHub Actions workflow defined in [`.github/workflows/check-urls.yml`](https://github.com/EbookFoundation/free-programming-books/blob/main/.github/workflows/check-urls.yml) that runs the `awesome_bot` tool on every push and pull request. This tool checks all URLs in the repository and reports failures, helping maintainers identify dead links before they affect users. ### What should I do if I find an archived version of a dead resource? If the original resource is permanently offline but available through the Internet Archive or similar services, include the archived URL in your Issue or Pull Request. The Wayback Machine link serves as a valid replacement that preserves the content while fixing the accessibility problem.