Errors

The site shows an error with its title, what happened and a link to its description here. Each description says what the error means and how to solve it. The webhooks answer GitHub with the same name, title and link, shown in the recent deliveries of the GitHub App. An error the site does not know is shown as UnexpectedError: please report it.

Pages of HTTP errors

Pages that do not exist (404), pages a visitor may not open (403), requests the site cannot understand (400), forms sent without the cookie of the site or left open too long (403) and failures of the site (500) have pages in the design of the site. Each shows the status, what happened, what to do, a link back to the start and one to report a bug. If the page of a failure cannot be shown with the menu, for example because the database is down, it is shown without the menu in the same colors; if even that fails, as plain text. The views are in ai_pycal/views/errors.py.

The configuration file

Errors of the configuration file of a repository: .github/agreements.yml.

Each of them is shown to the administrator who adds the repository, and in the list of repositories until the file is fixed. The format of the file is described in The configuration file.

exception ai_pycal.errors.config_file.ConfigFileError(detail: str = '', **context)

Bases: AgreementError

The configuration file of the repository can not be used.

Fix the file in the default branch of the repository as described in The configuration file and refresh the repository on the page Setup.

exception ai_pycal.errors.config_file.ConfigFileNotFound(detail: str = '', **context)

Bases: ConfigFileError

The repository has no configuration file.

A repository can only be added when its default branch contains the file .github/agreements.yml. Add the file, as in the example of The configuration file, and add the repository again.

exception ai_pycal.errors.config_file.ConfigFileNotYAML(detail: str = '', **context)

Bases: ConfigFileError

The configuration file is not valid YAML.

The detail names the line where the YAML can not be read. Check the indentation and the quotes there, for example with python -c "import yaml, sys; yaml.safe_load(open(sys.argv[1]))" .github/agreements.yml.

exception ai_pycal.errors.config_file.ConfigFileNotAMapping(detail: str = '', **context)

Bases: ConfigFileError

The configuration file does not contain a mapping of keys and values.

The file starts with version: and agreements:, each at the start of a line. A list or a single value is not a configuration.

exception ai_pycal.errors.config_file.ConfigVersionMissing(detail: str = '', **context)

Bases: ConfigFileError

The configuration file has no version.

The version says which format the file uses, so that later formats can be read without misunderstanding older files. Add version: 1.0.0 as the first line.

exception ai_pycal.errors.config_file.ConfigVersionInvalid(detail: str = '', **context)

Bases: ConfigFileError

The version of the configuration file is not a version number.

The version has three numbers separated by dots, such as 1.0.0. Put it in quotes if YAML reads it as a number: version: "1.0" is read as text.

exception ai_pycal.errors.config_file.ConfigVersionUnsupported(detail: str = '', **context)

Bases: ConfigFileError

This site does not know the major version of the configuration file.

The site reads the versions listed in The configuration file. A file of a newer major version can only be read by a newer version of the site: use the newest version the site supports, or ask the people who run the site to update it.

exception ai_pycal.errors.config_file.UnknownConfigKey(detail: str = '', **context)

Bases: ConfigFileError

The configuration file contains a key this version of the format does not have.

This is mostly a typing error, such as agreement: instead of agreements:. The detail names the key and where it is. Keys of newer minor versions are ignored: raise version only together with the keys.

exception ai_pycal.errors.config_file.NoAgreements(detail: str = '', **context)

Bases: ConfigFileError

The configuration file lists no agreements.

Add at least one agreement under agreements:, with an identifier as key and the fields name, repository, path and pr.

exception ai_pycal.errors.config_file.InvalidAgreementId(detail: str = '', **context)

Bases: ConfigFileError

The identifier of an agreement is not allowed.

Identifiers are the keys under agreements:. They contain lowercase letters, digits, - and _, start with a letter or a digit and are at most 50 characters long, such as ai-policy or cla.

exception ai_pycal.errors.config_file.AgreementNotAMapping(detail: str = '', **context)

Bases: ConfigFileError

An agreement of the configuration file is not a mapping.

Each agreement is a mapping of the fields name, ref, repository, path and pr, indented below its identifier.

exception ai_pycal.errors.config_file.MissingAgreementField(detail: str = '', **context)

Bases: ConfigFileError

An agreement lacks a field it needs.

The detail names the agreement and the field. name and path are required; ref defaults to the default branch and repository to the repository of the configuration file. Version 1 also requires pr.tags.

exception ai_pycal.errors.config_file.InvalidAgreementField(detail: str = '', **context)

Bases: ConfigFileError

A field of an agreement has a value of the wrong kind.

The detail names the agreement, the field and what is expected, for example text instead of a list. Text can be put in quotes.

exception ai_pycal.errors.config_file.InvalidAgreementPath(detail: str = '', **context)

Bases: ConfigFileError

The path of an agreement is not a path of a file in a repository.

The path is relative to the root of the repository, such as agreements/ai-policy.md. It does not start with / and contains no ...

exception ai_pycal.errors.config_file.InvalidLabel(detail: str = '', **context)

Bases: ConfigFileError

A label of pr.labels can not be a label of GitHub.

Labels of GitHub are at most 50 characters long and not empty. pr.labels is one label or a list of labels, such as ai-policy-accepted.

exception ai_pycal.errors.config_file.UnsupportedRemote(detail: str = '', **context)

Bases: ConfigFileError

The repository of an agreement is not on GitHub.

The agreements are read from GitHub. Use the address of a repository on GitHub, such as https://github.com/PyCalendar/ai.pycal.org-example.git or git@github.com:PyCalendar/ai.pycal.org-example.git.

exception ai_pycal.errors.config_file.AgreementRefNotFound(detail: str = '', **context)

Bases: ConfigFileError

The reference of an agreement does not exist in its repository.

ref names a tag, a branch or a commit of the repository of the agreement. Check the spelling and that it was pushed: git push origin <tag>. A private repository of the agreement needs the GitHub App installed on it.

exception ai_pycal.errors.config_file.AgreementFileNotFound(detail: str = '', **context)

Bases: ConfigFileError

The file of an agreement does not exist at its reference.

The file path is read from the repository of the agreement at the commit of ref. Check the path and that the file is part of that commit.

exception ai_pycal.errors.config_file.AgreementFileTooLarge(detail: str = '', **context)

Bases: ConfigFileError

The file of an agreement is too large.

People read the whole agreement before they accept it. Files of more than 200 KB are refused: split the agreement or link to the details.

exception ai_pycal.errors.config_file.AgreementFileNotText(detail: str = '', **context)

Bases: ConfigFileError

The file of an agreement is not text in UTF-8.

Agreements are shown as Markdown or as text. Save the file as UTF-8 text, such as Markdown with the extension .md.

Signing

Errors of signing an agreement.

Agreements are signed by people on the page of the agreement, never by a program; see Signing an agreement.

exception ai_pycal.errors.signing.SigningError(detail: str = '', **context)

Bases: AgreementError

The agreement could not be signed.

Read the agreement on its page, tick the box and type your GitHub handle, as described in Sign an agreement.

exception ai_pycal.errors.signing.NotAccepted(detail: str = '', **context)

Bases: SigningError

The box to accept the agreement was not ticked.

Tick the box “I have read and accept this agreement” below the agreement to sign it.

exception ai_pycal.errors.signing.HandleMismatch(detail: str = '', **context)

Bases: SigningError

The typed handle is not the GitHub handle you are signed in with.

Type your GitHub handle, as shown in the menu, to confirm that you sign yourself. Upper and lower case do not matter, @ can be left out.

exception ai_pycal.errors.signing.AgreementNotShown(detail: str = '', **context)

Bases: SigningError

The agreement was not shown to you before signing.

An agreement can only be signed from its page, after it was shown. Open the agreement, read it and sign it there. Signing is not possible with a program.

exception ai_pycal.errors.signing.AgreementVersionNotRequired(detail: str = '', **context)

Bases: SigningError

No repository asks for this version of the agreement.

The agreement was changed since the page was opened, or the repositories that asked for it were removed. Open the agreement from the pull request again to sign the version that is asked for now.

exception ai_pycal.errors.signing.AgreementNotFound(detail: str = '', **context)

Bases: SigningError

There is no agreement with this address.

Open the agreement from the pull request: the check of the site links to the agreements it needs.

exception ai_pycal.errors.signing.PullRequestNotFound(detail: str = '', **context)

Bases: SigningError

The site does not know this pull request.

The site knows the pull requests of the repositories that were added, from the moment they were added. Push a new commit to the pull request, or close and reopen it, so that GitHub tells the site about it.

exception ai_pycal.errors.signing.SignedTooFast(detail: str = '', **context)

Bases: SigningError

The agreement was signed faster than it can be read.

Signing is for people who read the agreement. Read it, then sign it again. The time is set by SIGN_MIN_SECONDS.

exception ai_pycal.errors.signing.SigningExpired(detail: str = '', **context)

Bases: SigningError

The page of the agreement was opened too long ago.

Load the page of the agreement again and sign it. The time is set by SIGN_MAX_HOURS.

Setting up repositories

Errors of setting up repositories, met by their administrators.

exception ai_pycal.errors.setup.SetupError(detail: str = '', **context)

Bases: AgreementError

The repository could not be set up.

Follow Set up a repository to install the GitHub App and add the repository.

exception ai_pycal.errors.setup.RepositoryNotFound(detail: str = '', **context)

Bases: SetupError

The site does not know this repository.

Add the repository on the page Setup first. Only repositories of installations that you administer are shown.

exception ai_pycal.errors.setup.InvalidNotificationEmail(detail: str = '', **context)

Bases: SetupError

The email address for notifications is not valid.

The site writes to this address when the GitHub App needs new permissions. Enter an address such as maintainers@example.org, or leave it empty.

exception ai_pycal.errors.setup.NotRepositoryAdmin(detail: str = '', **context)

Bases: SetupError

You do not administer this repository on GitHub.

Only people with the role admin or maintain of a repository can add it, change it or remove it. Ask an administrator of the repository.

GitHub

Errors of the answers of GitHub and of the GitHub App.

exception ai_pycal.errors.github.GitHubError(detail: str = '', **context)

Bases: AgreementError

GitHub answered with an error.

The detail contains the answer of GitHub. Try again later; if it stays, report a bug with the detail.

exception ai_pycal.errors.github.GitHubUnreachable(detail: str = '', **context)

Bases: GitHubError

GitHub could not be reached.

The network or GitHub is down. See https://www.githubstatus.com/ and try again later.

exception ai_pycal.errors.github.GitHubRateLimited(detail: str = '', **context)

Bases: GitHubError

GitHub allows no more requests for now.

The GitHub App has used all requests GitHub allows in an hour. The pull requests are checked again on their next change; try again in an hour.

exception ai_pycal.errors.github.GitHubAnswerNotJSON(detail: str = '', **context)

Bases: GitHubError

GitHub answered with something that is not JSON.

This happens when GitHub is partly down or a proxy answered. Try again later.

exception ai_pycal.errors.github.GitHubFileHistoryInvalid(detail: str = '', **context)

Bases: GitHubError

GitHub returned an invalid commit in an agreement file’s history.

The site cannot identify the agreement’s last edit safely. Try again later; if the problem continues, report a bug with the repository and file path.

exception ai_pycal.errors.github.GitHubAppNotConfigured(detail: str = '', **context)

Bases: AgreementError

The site has no GitHub App.

The people who run the site set GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEY, GITHUB_CLIENT_ID, GITHUB_SECRET and GITHUB_WEBHOOK_SECRET as described in Set up the GitHub App.

exception ai_pycal.errors.github.SignInNotConfigured(detail: str = '', **context)

Bases: GitHubAppNotConfigured

Signing in with GitHub is not configured.

The site signs people in with the GitHub App. Set GITHUB_CLIENT_ID and GITHUB_SECRET to the client ID and a client secret of the app, as described in Set up the GitHub App. For development, put them into .env: make run reads it.

exception ai_pycal.errors.github.InvalidPrivateKey(detail: str = '', **context)

Bases: GitHubAppNotConfigured

The private key of the GitHub App can not be read.

GITHUB_APP_PRIVATE_KEY contains the whole PEM file that GitHub generated for the app, from -----BEGIN RSA PRIVATE KEY----- to the end, or GITHUB_APP_PRIVATE_KEY_FILE names that file. Generate a new key on the page of the app if it was lost.

exception ai_pycal.errors.github.InstallationNotFound(detail: str = '', **context)

Bases: AgreementError

GitHub does not know this installation of the GitHub App.

The app was uninstalled, or the address of the setup was changed. Install the app again from the page Setup.

exception ai_pycal.errors.github.InstallationNotYours(detail: str = '', **context)

Bases: AgreementError

You can not administer this installation of the GitHub App.

Only people who can manage the GitHub App on an account or organization, such as its owners, can add its repositories. Ask an owner to install the app, or to make you an app manager of the organization.

exception ai_pycal.errors.github.RepositoryNotInstalled(detail: str = '', **context)

Bases: AgreementError

The GitHub App is not installed on this repository.

Repositories can only be added if the app can read them and label their pull requests. Add the repository to the installation on GitHub, then refresh the page Setup.

exception ai_pycal.errors.github.MissingPermissions(detail: str = '', **context)

Bases: AgreementError

The GitHub App lacks permissions it needs.

A new version of the site needs more permissions than were accepted when the app was installed. The administrators of the installation got an email: open the installation on GitHub and accept the new permissions. Which permissions are needed is listed in Permissions of the GitHub App.

exception ai_pycal.errors.github.GitHubNotFound(detail: str = '', **context)

Bases: GitHubError

GitHub does not know what was asked for, or the GitHub App may not read it.

The repository, the branch, the tag or the file does not exist, or it is private and the app is not installed on it.

exception ai_pycal.errors.github.GitHubLoginExpired(detail: str = '', **context)

Bases: AgreementError

Your sign in with GitHub has expired.

The site asks GitHub which installations you manage with the token of your sign in. The site renews expiring tokens automatically, but a missing, expired or revoked refresh token requires a new sign in. Sign out and sign in with GitHub again.

exception ai_pycal.errors.github.GitHubTokenResponseInvalid(detail: str = '', **context)

Bases: GitHubError

GitHub did not return valid replacement user tokens.

The token renewal response is missing an access token, refresh token or positive lifetime. Try again later; if it continues, report a bug. Sign out and sign in again to obtain new credentials.

exception ai_pycal.errors.github.CannotWriteLabels(detail: str = '', **context)

Bases: GitHubError

The GitHub App could not update the pull request’s labels.

Check that the app is installed on this repository with pull_requests: write permission and is not suspended. Accept any pending permission update on GitHub, then refresh the project on Setup to retry its open pull requests.

Webhooks

Errors of the webhooks that GitHub sends to the site.

GitHub shows them in the list of recent deliveries of the GitHub App, with the status of the answer.

exception ai_pycal.errors.webhooks.WebhookError(detail: str = '', **context)

Bases: AgreementError

A webhook of GitHub could not be handled.

See the recent deliveries in the advanced settings of the GitHub App for the answer, and Set up the GitHub App for the setup.

exception ai_pycal.errors.webhooks.WebhookSecretNotConfigured(detail: str = '', **context)

Bases: WebhookError

The site has no secret to check the webhooks with.

Without GITHUB_WEBHOOK_SECRET anybody could send webhooks to the site, so they are refused. Set it to the webhook secret of the GitHub App.

exception ai_pycal.errors.webhooks.WebhookSignatureMissing(detail: str = '', **context)

Bases: WebhookError

The webhook has no signature.

GitHub signs every webhook with the secret of the app in the header X-Hub-Signature-256. Set a webhook secret in the settings of the GitHub App.

exception ai_pycal.errors.webhooks.WebhookSignatureInvalid(detail: str = '', **context)

Bases: WebhookError

The signature of the webhook does not match the secret.

The webhook secret of the GitHub App and GITHUB_WEBHOOK_SECRET of the site differ. Set both to the same value.

exception ai_pycal.errors.webhooks.WebhookPayloadInvalid(detail: str = '', **context)

Bases: WebhookError

The content of the webhook is not the JSON GitHub sends.

Check that the content type of the webhook of the GitHub App is application/json.

Settings of the site

Errors of the settings of the site, met by the people who run it.

The site does not start with them; the message names the setting. All settings are listed in Settings.

exception ai_pycal.errors.configuration.ConfigurationError(detail: str = '', **context)

Bases: AgreementError

A setting of the site is invalid.

Fix the setting in the environment, such as the file .env, and start the site again. All settings are listed in Settings.

exception ai_pycal.errors.configuration.InvalidColor(detail: str = '', **context)

Bases: ConfigurationError

A color of the theme is not a color.

The colors of the site are set with COLOR_... settings, such as COLOR_PRIMARY=#3b79aa. Use # and three or six hexadecimal digits. See Change the colors and the icon.

exception ai_pycal.errors.configuration.UnknownColor(detail: str = '', **context)

Bases: ConfigurationError

A COLOR_... setting names a color the theme does not have.

The names of the colors are listed in Change the colors and the icon, such as COLOR_PRIMARY or COLOR_DARK_PRIMARY. Check the spelling.

exception ai_pycal.errors.configuration.FaviconNotFound(detail: str = '', **context)

Bases: ConfigurationError

The file of FAVICON does not exist.

FAVICON is an address such as https://pycal.org/favicon.png, or the path of a PNG, ICO or SVG file inside the container, such as /app/data/favicon.png in the volume of the data. See Change the colors and the icon.

exception ai_pycal.errors.configuration.UnsupportedFavicon(detail: str = '', **context)

Bases: ConfigurationError

The file of FAVICON is not a PNG, ICO or SVG file.

Browsers show these formats as icon of the page. Convert the icon and name the file with its extension: .png, .ico or .svg.

exception ai_pycal.errors.configuration.InvalidFooterLink(detail: str = '', **context)

Bases: ConfigurationError

An entry of FOOTER_LINKS is not Title=URL.

FOOTER_LINKS lists the extra links of the footer and the About page, separated by commas, each as a title, = and an address that starts with https:// or http://, such as FOOTER_LINKS=pycal.org=https://pycal.org,Blog=https://example.org/blog/. Leave it empty for no extra links. See Settings.

All errors

The base of all errors.

exception ai_pycal.errors.base.AgreementError(detail: str = '', **context)

Bases: Exception

Something went wrong.

This is the base of all errors. If you see it, please report a bug with “Report a bug” at the bottom of the page.

exception ai_pycal.errors.base.UnexpectedError(detail: str = '', **context)

Bases: AgreementError

An error that this site does not know.

This is a bug. Please report it with “Report a bug” at the bottom of the page and include the message.

Policy choices

Errors in policy choices and changes made by contributors.

exception ai_pycal.errors.choices.InvalidMandatory(detail: str = '', **context)

Bases: ConfigFileError

An agreement’s mandatory flag is not a boolean.

Use the YAML value true or false without quotes for mandatory. Mandatory agreements apply to every pull request regardless of the selected choice.

exception ai_pycal.errors.choices.InvalidChoices(detail: str = '', **context)

Bases: ConfigFileError

The choices field is not a list of mappings.

Write choices as a YAML list. Each entry needs a unique name, a description, and a nonempty list of agreement identifiers, as in the configuration guide.

exception ai_pycal.errors.choices.InvalidChoiceField(detail: str = '', **context)

Bases: ConfigFileError

A choice has a missing or invalid field.

Give each choice a name, a Markdown description and a nonempty agreements list. Its default flag must be true or false. The detail names the field.

exception ai_pycal.errors.choices.UnknownChoiceAgreement(detail: str = '', **context)

Bases: ConfigFileError

A choice references an agreement that is not defined.

Every identifier in a choice’s agreements list must be a key under agreements in the same configuration. Correct the spelling or define it.

exception ai_pycal.errors.choices.DuplicateChoice(detail: str = '', **context)

Bases: ConfigFileError

Two choices have the same name or normalized identifier.

Use distinct choice names. Names become lowercase identifiers with words separated by hyphens, so punctuation alone cannot distinguish two choices.

exception ai_pycal.errors.choices.MultipleDefaultChoices(detail: str = '', **context)

Bases: ConfigFileError

More than one choice is marked as the project default.

Set default to true for at most one choice. Contributors may choose their own project default and override it on individual pull requests.

exception ai_pycal.errors.choices.ChoiceNotFound(detail: str = '', **context)

Bases: SigningError

The selected choice is no longer offered by this project.

Reload the pull request page and select one of the current choices. The project configuration may have changed since the form was opened.

exception ai_pycal.errors.choices.NotPullRequestAuthor(detail: str = '', **context)

Bases: SigningError

Only the pull request author may change its policy choice or sign for it.

Sign in with the GitHub account that authored this pull request. Maintainers can view signatures but cannot select policies or sign on another person’s behalf.

exception ai_pycal.errors.choices.ChoiceNotAMapping(detail: str = '', **context)

Bases: InvalidChoiceField

A choices list entry is not a mapping of fields.

Replace the entry with a mapping containing name, description and agreements. Every choice must define its own fields below the list marker.

exception ai_pycal.errors.choices.InvalidChoiceName(detail: str = '', **context)

Bases: InvalidChoiceField

A choice name is empty, too long or cannot form a stable identifier.

Use a name of at most 200 characters with letters or digits. Its normalized lowercase hyphenated identifier must contain between one and fifty characters.

exception ai_pycal.errors.choices.InvalidChoiceDescription(detail: str = '', **context)

Bases: InvalidChoiceField

A choice lacks a nonempty Markdown description.

Add description as a text value explaining the choice to contributors. Put multiline Markdown in a YAML block scalar introduced with a vertical bar.

exception ai_pycal.errors.choices.InvalidChoiceAgreements(detail: str = '', **context)

Bases: InvalidChoiceField

A choice does not list the agreements it requires.

Set agreements to a nonempty YAML list of policy identifiers, such as agreements: [ai-policy]. Each identifier must exist under agreements.

exception ai_pycal.errors.choices.InvalidChoiceDefault(detail: str = '', **context)

Bases: InvalidChoiceField

A choice’s default flag is not a YAML boolean.

Set default to true or false without quotes. Leave the field out to use false. At most one configured choice may have default set to true.