Exceptions

The pythonanywhere-core library defines custom exception types for different error scenarios.

Exception Hierarchy

Exception
├── AuthenticationError
├── SanityException
└── PythonAnywhereApiException
    ├── NoTokenError
    └── DomainAlreadyExistsException

Exception Reference

exception exceptions.AuthenticationError[source]

Bases: Exception

exception exceptions.DomainAlreadyExistsException[source]

Bases: PythonAnywhereApiException

exception exceptions.MissingCNAMEException[source]

Bases: PythonAnywhereApiException

exception exceptions.NoTokenError[source]

Bases: PythonAnywhereApiException

exception exceptions.PythonAnywhereApiException[source]

Bases: Exception

exception exceptions.SanityException[source]

Bases: Exception

Detailed Descriptions

AuthenticationError

class exceptions.AuthenticationError(Exception)[source]

Raised when API authentication fails.

When raised:

  • API returns a 401 Unauthorized status code

  • Invalid or expired API token

Common causes:

  • Incorrect API_TOKEN environment variable

  • Expired API token

  • Token doesn’t have required permissions

Example:

from pythonanywhere_core.base import call_api
from pythonanywhere_core.exceptions import AuthenticationError
import os

os.environ["API_TOKEN"] = "invalid_token"

try:
    call_api("https://www.pythonanywhere.com/api/v0/user/myuser/webapps/", "get")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
Resolution:

  • Verify your API token is correct

  • Generate a new token from the PythonAnywhere Account page

  • Ensure the token is properly set in the environment

SanityException

class exceptions.SanityException(Exception)[source]

Raised when pre-flight sanity checks fail.

When raised:

  • Attempting to create a webapp that already exists (without nuke flag)

  • Missing API token during sanity checks

  • Invalid configuration detected before API operations

Common causes:

  • Trying to create duplicate resources

  • Environment not properly configured

Example:

from pythonanywhere_core.webapp import Webapp
from pythonanywhere_core.exceptions import SanityException

webapp = Webapp("myuser.pythonanywhere.com")

try:
    webapp.sanity_checks(nuke=False)
except SanityException as e:
    print(f"Sanity check failed: {e}")
    # Use nuke=True to overwrite existing webapp
Resolution:

  • Use the nuke parameter to overwrite existing resources

  • Ensure API token is properly configured

  • Check that resources don’t already exist

PythonAnywhereApiException

class exceptions.PythonAnywhereApiException(Exception)[source]

Base exception for all PythonAnywhere API-related errors.

When raised:

  • Generic API operation failures

  • Unexpected API responses

  • Network or HTTP errors from the API

Common causes:

  • API endpoint unreachable

  • Malformed API requests

  • Server-side errors

Example:

from pythonanywhere_core.webapp import Webapp
from pythonanywhere_core.exceptions import PythonAnywhereApiException

webapp = Webapp("myuser.pythonanywhere.com")

try:
    webapp.reload()
except PythonAnywhereApiException as e:
    print(f"API operation failed: {e}")
Resolution:

  • Check the error message for specific details

  • Verify API endpoint URLs are correct

  • Ensure your account has required permissions

NoTokenError

class exceptions.NoTokenError(PythonAnywhereApiException)[source]

Raised when the API_TOKEN environment variable is not set.

When raised:

  • Any API call attempt without API_TOKEN environment variable

Common causes:

  • Forgot to set environment variable

  • Running in a new shell session where variable wasn’t exported

  • Environment variable was unset

Example:

import os
from pythonanywhere_core.base import call_api
from pythonanywhere_core.exceptions import NoTokenError

# Unset token to demonstrate
if "API_TOKEN" in os.environ:
    del os.environ["API_TOKEN"]

try:
    call_api("https://www.pythonanywhere.com/api/v0/user/myuser/webapps/", "get")
except NoTokenError as e:
    print(f"Token not found: {e}")
Resolution:

  • Set the API_TOKEN environment variable:

    export API_TOKEN="your_token_here"

  • See Environment Variables for detailed setup instructions

DomainAlreadyExistsException

class exceptions.DomainAlreadyExistsException(PythonAnywhereApiException)[source]

Raised when attempting to create a domain that already exists.

When raised:

  • Creating a website/domain that is already registered

Common causes:

  • Domain was previously created

  • Domain exists in your account

Resolution:

  • Check existing domains before creating new ones

  • Delete the existing domain first if you want to recreate it

  • Use a different domain name

Best Practices

Exception Handling

Always catch specific exceptions rather than generic Exception:

from pythonanywhere_core.webapp import Webapp
from pythonanywhere_core.exceptions import (
    NoTokenError,
    AuthenticationError,
    PythonAnywhereApiException
)

webapp = Webapp("myuser.pythonanywhere.com")

try:
    webapp.reload()
except NoTokenError:
    print("Please set your API_TOKEN environment variable")
except AuthenticationError:
    print("Invalid API token - please generate a new one")
except PythonAnywhereApiException as e:
    print(f"API error: {e}")

Graceful Degradation

Handle errors gracefully in production code:

import sys
from pythonanywhere_core.exceptions import SanityException

webapp = Webapp("myuser.pythonanywhere.com")

try:
    webapp.sanity_checks(nuke=False)
    webapp.create(python_version="3.10", virtualenv_path=venv, project_path=path, nuke=False)
except SanityException as e:
    print(f"Error: {e}")
    print("Use --nuke flag to overwrite existing webapp")
    sys.exit(1)

See Also