Why does my GitHub release fail with an error?

    Before troubleshooting a failed GitHub release, make sure you have read and understood the documentation on how to archive a GitHub release in Zenodo, and how to use CITATION.cff and the Zenodo JSON file to provide additional metadata when releasing software.

    A GitHub release can fail for several reasons. The first step is to identify the error message. You can find it in the Errors tab of the Zenodo panel in GitHub.

    Common error messages include:

    1. “Extra metadata load failed.”

      This indicates that the Zenodo JSON file in your GitHub repository is invalid. Refer to the Zenodo JSON documentation to identify and fix the issue.

    2. “Citation metadata load failed.”

      This indicates that the CITATION.cff file in your GitHub repository is invalid. Refer to the CITATION.cff documentation to understand what needs to be corrected.

    3. "": An empty error message.

      This is a known issue. A permanent fix is planned for 2026 as part of the Zenodo development roadmap.

    In most cases, release failures are related to missing or invalid metadata. When releasing software for the first time, or when publishing a new version of an existing record, Zenodo may require specific metadata fields. These fields can be provided by adding a CITATION.cff file, which is the preferred approach, or a Zenodo JSON file if the missing information relates to funding, Zenodo communities, access settings, or related identifiers.

    Please note that if your repository contains both a CITATION.cff file and a .zenodo.json file, Zenodo will only use the .zenodo.json metadata. The CITATION.cff file will be ignored for GitHub release archiving.

    Example of required metadata fields

    If your Zenodo record belongs to a project in the EU Open Research Repository (EU-funded communities), funding information is mandatory. Other Zenodo communities may enforce additional required fields. If you are unsure which fields are required, contact the community owners for guidance.

    If required metadata is missing, the release may fail with an empty error message.

    To fix this issue for EU Open Research Repository projects (EU-funded communities), follow these steps:

    1. Create a .zenodo.json file in your GitHub repository.

    2. Add the funding information for the relevant project, for example:


    {
           ...
           "grants": [
                   { "id": "<funding-id>" }
           ]
           ...
    }

    3. Add other important metadata such as creators, contributors, or license information, as described in the Zenodo JSON documentation.
    4. Re-create the release in GitHub.

    After completing these steps, your software release should be archived successfully in Zenodo.

    Published