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:
DashboardErrorNot 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:
DashboardErrorInvalid 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:
DashboardErrorThe 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:
AccountErrorThe 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:
AccountErrorUnknown 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:
DashboardErrorThe 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:
RegistrationErrorThe 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 theGITHUB_...settings from both and restart the site.
- exception pycal_dashboard.errors.registration.PrivateKeyFileExists(detail: str = '', **context)#
Bases:
RegistrationErrorA 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_FILEor toDATA_DIR/github-app.pemand never overwrites a file. A file there is the key of another app: set theGITHUB_...settings of that app, or move the file away and register again.
- exception pycal_dashboard.errors.registration.AppSettingsInEnvironment(detail: str = '', **context)#
Bases:
RegistrationErrorSettings 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:
RegistrationErrorThe 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_codeshows it, such as withdocker compose exec dashboard python manage.py github_app_setup_code.
- exception pycal_dashboard.errors.registration.InvalidAppName(detail: str = '', **context)#
Bases:
RegistrationErrorThe 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:
RegistrationErrorThe 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:
RegistrationErrorThe 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:
RegistrationErrorGitHub returned without a code · HTTP 400
Why it appears: GitHub returned without the code of the new app.
How to resolve it: GitHub adds
codeto 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:
RegistrationErrorGitHub 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:
RegistrationErrorThe 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 theGITHUB_...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:
DashboardErrorGitHub 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:
GitHubErrorGitHub 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:
GitHubErrorNot 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:
GitHubErrorGitHub 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:
GitHubErrorToo 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:
GitHubErrorThe 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:
GitHubErrorSigning 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_IDandGITHUB_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:
GitHubErrorThe 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:
GitHubErrorThe 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_KEYor the file ofGITHUB_APP_PRIVATE_KEY_FILEis 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:
DashboardErrorThe 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:
WebhookErrorThe 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_SECRETanybody 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:
WebhookErrorThe 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:
WebhookErrorThe 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_SECRETof the site differ. Set both to the same value.
- exception pycal_dashboard.errors.webhooks.WebhookPayloadInvalid(detail: str = '', **context)#
Bases:
WebhookErrorThe 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:
WebhookErrorThe 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:
DashboardErrorA 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:
ConfigurationErrorUnknown 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_PRIMARYorCOLOR_DARK_ACCENT.
- exception pycal_dashboard.errors.configuration.InvalidColor(detail: str = '', **context)#
Bases:
ConfigurationErrorInvalid 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:
ConfigurationErrorInvalid organization in the settings · HTTP 500
Why it appears:
GITHUB_ORGANIZATIONScontains 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:
ConfigurationErrorThe favicon was not found · HTTP 500
Why it appears: The file of
FAVICONdoes not exist.How to resolve it:
FAVICONis an address such ashttps://pycal.org/favicon.png, or the path of a PNG, ICO or SVG file inside the container, such as/app/data/favicon.pngin the volume of the data. See Settings.
- exception pycal_dashboard.errors.configuration.UnsupportedFavicon(detail: str = '', **context)#
Bases:
ConfigurationErrorThe favicon has an unsupported format · HTTP 500
Why it appears: The file of
FAVICONis 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,.icoor.svg.
Bases:
ConfigurationErrorA link of the footer is invalid · HTTP 500
Why it appears: An entry of
FOOTER_LINKSis notTitle=URL.How to resolve it:
FOOTER_LINKSlists the extra links of the footer, separated by commas, each as a title,=and an address that starts withhttps://orhttp://, such asFOOTER_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:
ExceptionSomething 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:
DashboardErrorUnexpected 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.