Errors#

Every error of the dashboard has its own entry here. The page of an error shows its title, what happened and a button What this error means and how to solve it, which leads to its entry. Each entry gives:

  • the title and the HTTP status of the page,

  • in its first sentence, why the error appears,

  • after it, how to resolve it.

The JSON of the pages and the webhooks answer errors as JSON with the same name, title and link:

{
  "error": "WebhookSignatureMissing",
  "title": "The webhook has no signature",
  "detail": "X-Hub-Signature-256",
  "documentation": "https://docs.dashboard.pycal.org/reference/errors.html#pycal_dashboard.errors.webhooks.WebhookSignatureMissing"
}

An error the site does not know is shown as UnexpectedError: please report it, see Report a bug.

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, it is shown without the menu in the same colors; if even that fails, as plain text.

Pages and API#

Errors of the pages and the API of the dashboard, met by visitors.

The pages show them with the HTTP status; the JSON of a page answers with the same name, title and link, see JSON of the pages.

exception pycal_dashboard.errors.dashboard.LookupFailed(detail: str = '', **context)#

Bases: DashboardError

Not found · HTTP 404

Why it appears: The page does not exist.

How to resolve it: Check the address, or start again from the start page.

exception pycal_dashboard.errors.dashboard.InvalidInstallationId(detail: str = '', **context)#

Bases: DashboardError

Invalid installation · HTTP 400

Why it appears: GitHub returned to the site without the number of the installation.

How to resolve it: GitHub opens /setup/installed/?installation_id=... after the GitHub App was installed. The address was changed or opened by hand. Install the app again from its page on GitHub, see Register the GitHub App and the OAuth app.

Account#

Errors of the account page, met by people who signed in.

exception pycal_dashboard.errors.account.AccountError(detail: str = '', **context)#

Bases: DashboardError

The account could not be changed · HTTP 400

Why it appears: The account could not be changed.

How to resolve it: Go back to the page Account, reload it and try again.

exception pycal_dashboard.errors.account.NoGitHubAccount(detail: str = '', **context)#

Bases: AccountError

The account has no GitHub identity · HTTP 403

Why it appears: The account has no GitHub identity.

How to resolve it: Accounts of the dashboard come from GitHub. This one was created another way, such as with manage.py createsuperuser. Sign out and sign in with GitHub.

exception pycal_dashboard.errors.account.UnknownPreference(detail: str = '', **context)#

Bases: AccountError

Unknown preference · HTTP 400

Why it appears: The form of the preferences sent a value that the site does not know.

How to resolve it: The detail names the field and its value. Reload the page Account: the form may be from an older version of the site, which knew other languages or colors.

Registering the GitHub App#

Errors of registering the GitHub App on the site, met by the people who run it.

The site registers its own GitHub App on /setup/github-app/, see Register the GitHub App and the OAuth app. Each page of an error has details to copy for a bug report.

exception pycal_dashboard.errors.registration.RegistrationError(detail: str = '', **context)#

Bases: DashboardError

The GitHub App could not be registered · HTTP 400

Why it appears: The GitHub App could not be registered.

How to resolve it: Start again on the page Register the GitHub App of the site, as Register the GitHub App and the OAuth app describes. If it fails again, copy the details of the page into a bug report.

exception pycal_dashboard.errors.registration.AppAlreadyRegistered(detail: str = '', **context)#

Bases: RegistrationError

The site already has a GitHub App · HTTP 409

Why it appears: The site already has a GitHub App.

How to resolve it: A site has one GitHub App. Its settings come from the environment or from DATA_DIR/.env, which the registration wrote. To use another app, remove the GITHUB_... settings from both and restart the site.

exception pycal_dashboard.errors.registration.PrivateKeyFileExists(detail: str = '', **context)#

Bases: RegistrationError

A private key exists already · HTTP 409

Why it appears: The file for the private key of the new app exists already.

How to resolve it: The registration writes the key to GITHUB_APP_PRIVATE_KEY_FILE or to DATA_DIR/github-app.pem and never overwrites a file. A file there is the key of another app: set the GITHUB_... settings of that app, or move the file away and register again.

exception pycal_dashboard.errors.registration.AppSettingsInEnvironment(detail: str = '', **context)#

Bases: RegistrationError

Settings of a GitHub App are set in the environment · HTTP 409

Why it appears: Settings of a GitHub App are set in the environment.

How to resolve it: The settings of the environment take precedence over those the registration writes, so the site would mix two apps. The detail names them. Remove them or leave them empty, restart the site and register again; or set all of them for an app that exists.

exception pycal_dashboard.errors.registration.SetupCodeWrong(detail: str = '', **context)#

Bases: RegistrationError

The setup code is wrong · HTTP 403

Why it appears: The setup code is missing or wrong.

How to resolve it: Only the people who run the site may register its GitHub App. The site writes the setup code into its log at every start while it has no app. manage.py github_app_setup_code shows it, such as with docker compose exec dashboard python manage.py github_app_setup_code.

exception pycal_dashboard.errors.registration.InvalidAppName(detail: str = '', **context)#

Bases: RegistrationError

The name of the GitHub App is invalid · HTTP 400

Why it appears: The name of the GitHub App is empty or too long.

How to resolve it: GitHub needs a name of at most 34 characters that no other GitHub App has, such as dashboard-pycal-org.

exception pycal_dashboard.errors.registration.InvalidOrganization(detail: str = '', **context)#

Bases: RegistrationError

The organization is invalid · HTTP 400

Why it appears: The organization is not a GitHub login.

How to resolve it: Enter the login of the organization, such as PyCalendar, or leave the field empty to register the app on your own account.

exception pycal_dashboard.errors.registration.RegistrationExpired(detail: str = '', **context)#

Bases: RegistrationError

The registration does not belong to this browser · HTTP 400

Why it appears: The return from GitHub does not belong to a registration of this browser.

How to resolve it: The site gives each registration a secret state and checks it when GitHub returns. It was missing or different: the registration was started in another browser, the session expired, or the page was opened twice. Start again.

exception pycal_dashboard.errors.registration.RegistrationCodeMissing(detail: str = '', **context)#

Bases: RegistrationError

GitHub returned without a code · HTTP 400

Why it appears: GitHub returned without the code of the new app.

How to resolve it: GitHub adds code to the address when the app was created. Without it, the registration was cancelled on GitHub. Start again.

exception pycal_dashboard.errors.registration.ManifestConversionFailed(detail: str = '', **context)#

Bases: RegistrationError

GitHub refused the code of the new app · HTTP 502

Why it appears: GitHub refused to hand out the credentials of the new app.

How to resolve it: The code of the return is valid for one hour and only once. Start again; if the app was created on GitHub, delete it there first.

exception pycal_dashboard.errors.registration.RegistrationNotSaved(detail: str = '', **context)#

Bases: RegistrationError

The GitHub App could not be saved · HTTP 500

Why it appears: The credentials of the new app could not be written into the data directory.

How to resolve it: The site writes them into DATA_DIR, the volume of the container. Make the directory writable for the user of the container. The app exists on GitHub: delete it there and register again, or generate a new private key and set the GITHUB_... settings yourself.

GitHub#

Errors of talking to GitHub, of the GitHub App and of signing in.

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

Bases: DashboardError

GitHub answered with an error · HTTP 502

Why it appears: GitHub answered a request of the site with an error.

How to resolve it: The detail shows the request and the answer of GitHub. If it happens again, check https://www.githubstatus.com/ and report a bug.

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

Bases: GitHubError

GitHub could not be reached · HTTP 503

Why it appears: The site could not reach GitHub.

How to resolve it: The network of the site or GitHub is down. Try again in a few minutes. The people who run the site check that the container can reach api.github.com.

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

Bases: GitHubError

Not found on GitHub · HTTP 404

Why it appears: GitHub does not know what the site asked for.

How to resolve it: The repository, pull request or installation was deleted, renamed or is not visible to the GitHub App.

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

Bases: GitHubError

GitHub did not accept the token · HTTP 502

Why it appears: GitHub did not accept the token of the site.

How to resolve it: The GitHub App was deleted, its private key was revoked, or the clock of the server is wrong. Check the settings of the GitHub App and the time of the server.

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

Bases: GitHubError

Too many requests to GitHub · HTTP 503

Why it appears: The site sent too many requests to GitHub.

How to resolve it: GitHub allows a number of requests per hour. Wait until the limit is reset, usually within an hour. The dashboard keeps showing what it read before.

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

Bases: GitHubError

The GitHub App lacks a permission · HTTP 403

Why it appears: The GitHub App may not do what the site needs.

How to resolve it: An installation lacks a permission that a request of the site needs. An owner of the organization accepts the new permissions in the settings of the installation on GitHub; Permissions of the GitHub App lists them.

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

Bases: GitHubError

Signing in is not set up · HTTP 503

Why it appears: Nobody can sign in: the site has no OAuth app.

How to resolve it: People sign in with a separate OAuth app of GITHUB_OAUTH_CLIENT_ID and GITHUB_OAUTH_SECRET. The people who run the site create it on GitHub and enter it on /setup/oauth-app/, which the button Set up signing in of the page of the error opens, with the setup code of the log, as Sign people in with the OAuth app describes.

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

Bases: GitHubError

The site has no GitHub App · HTTP 503

Why it appears: The site has no GitHub App yet.

How to resolve it: The site needs its GitHub App to receive the webhooks and to read what GitHub knows about the app. Register it on the page Register the GitHub App (/setup/github-app/), which the button of the page of the error opens, with the setup code from the log of the site, as Register the GitHub App and the OAuth app describes.

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

Bases: GitHubError

The private key of the GitHub App is invalid · HTTP 500

Why it appears: The private key of the GitHub App cannot sign.

How to resolve it: GITHUB_APP_PRIVATE_KEY or the file of GITHUB_APP_PRIVATE_KEY_FILE is not the PEM key that GitHub generated for the app. Generate a new key in the settings of the app on GitHub and set it.

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. The site keeps them on the page Webhook deliveries for its administrators.

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

Bases: DashboardError

The webhook could not be handled · HTTP 400

Why it appears: A webhook of GitHub could not be handled.

How to resolve it: See the recent deliveries in the advanced settings of the GitHub App for the answer, and Register the GitHub App and the OAuth app for the setup.

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

Bases: WebhookError

The site has no webhook secret · HTTP 503

Why it appears: The site has no secret to check the webhooks with.

How to resolve it: 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 pycal_dashboard.errors.webhooks.WebhookSignatureMissing(detail: str = '', **context)#

Bases: WebhookError

The webhook has no signature · HTTP 401

Why it appears: The webhook has no signature.

How to resolve it: 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 pycal_dashboard.errors.webhooks.WebhookSignatureInvalid(detail: str = '', **context)#

Bases: WebhookError

The signature of the webhook is invalid · HTTP 401

Why it appears: The signature of the webhook does not match the secret.

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

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

Bases: WebhookError

The content of the webhook is invalid · HTTP 400

Why it appears: The content of the webhook is not the JSON object GitHub sends.

How to resolve it: Check that the content type of the webhook of the GitHub App is application/json.

exception pycal_dashboard.errors.webhooks.WebhookEventMissing(detail: str = '', **context)#

Bases: WebhookError

The webhook names no event · HTTP 400

Why it appears: The webhook does not say which event it is.

How to resolve it: GitHub names the event in the header X-GitHub-Event. A request without it does not come from GitHub.

Settings of the site#

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

The settings are environment variables, listed in Settings.

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

Bases: DashboardError

A setting of the site is wrong · HTTP 500

Why it appears: A setting of the site is wrong.

How to resolve it: The detail names the setting. Correct it in the environment, such as in .env, and restart the site.

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

Bases: ConfigurationError

Unknown color · HTTP 500

Why it appears: A COLOR_... setting names a color that the theme does not have.

How to resolve it: The detail lists the known names. Use one of them, such as COLOR_PRIMARY or COLOR_DARK_ACCENT.

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

Bases: ConfigurationError

Invalid color · HTTP 500

Why it appears: A COLOR_... setting is not a color.

How to resolve it: Write colors with # and three or six hexadecimal digits, such as #3b79aa.

exception pycal_dashboard.errors.configuration.InvalidOrganizationSetting(detail: str = '', **context)#

Bases: ConfigurationError

Invalid organization in the settings · HTTP 500

Why it appears: GITHUB_ORGANIZATIONS contains something that is not a GitHub login.

How to resolve it: Write the logins of the organizations, separated by commas, such as PyCalendar.

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

Bases: ConfigurationError

The favicon was not found · HTTP 500

Why it appears: The file of FAVICON does not exist.

How to resolve it: 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 Settings.

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

Bases: ConfigurationError

The favicon has an unsupported format · HTTP 500

Why it appears: The file of FAVICON is not a PNG, ICO or SVG file.

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

Bases: ConfigurationError

A link of the footer is invalid · HTTP 500

Why it appears: An entry of FOOTER_LINKS is not Title=URL.

How to resolve it: FOOTER_LINKS lists the extra links of the footer, 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 pycal_dashboard.errors.base.DashboardError(detail: str = '', **context)#

Bases: Exception

Something went wrong · HTTP 400

Why it appears: Something went wrong.

How to resolve it: 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.

classmethod setup_url() → str#

The page of the site that solves the error, such as the setup of the GitHub App.

Returns:

Its address, “” for errors without one.

Examples:
>>> from pycal_dashboard.errors import SignInNotConfigured
>>> SignInNotConfigured.setup_url(), UnexpectedError.setup_url()
('/setup/oauth-app/', '')
exception pycal_dashboard.errors.base.UnexpectedError(detail: str = '', **context)#

Bases: DashboardError

Unexpected error · HTTP 500

Why it appears: An error that this site does not know.

How to resolve it: This is a bug. Please report it with “Report a bug” at the bottom of the page and include the details of the page.