Skip to content
al-falak

Errors

Errors

Section titled “Errors”

Al-Falak uses a dedicated error hierarchy for all failures. All errors inherit from AlFalakError.

Error hierarchy

Section titled “Error hierarchy”
AlFalakError (base)
├── AstronomicalError    # Sun position undefined (polar day/night)
├── ConfigurationError   # Invalid setup (method, madhab, etc.)
└── ValidationError      # Out-of-range input (coordinates, angles)

Catching errors

Section titled “Catching errors”
from alfalak import PrayerTimes, CalculationMethod, AlFalakError


try:
    pt = PrayerTimes((35.7750, -78.6336), datetime.now(), CalculationMethod.NORTH_AMERICA)
except AlFalakError as e:
    print(f"Calculation failed: {e}")

Specific error types

Section titled “Specific error types”

AstronomicalError

Section titled “AstronomicalError”

Raised when the sun never rises or sets (polar day/night) and PolarCircleRule.NONE is set:

from alfalak import AstronomicalError, PolarCircleRule, CalculationParameters


params = CalculationParameters(polar_circle_rule=PolarCircleRule.NONE)
try:
    PrayerTimes((78.2232, 15.6267), datetime.now(), calculation_parameters=params)
except AstronomicalError as e:
    print(f"Polar day/night: {e}")

ConfigurationError

Section titled “ConfigurationError”

Raised for invalid configuration:

from alfalak import ConfigurationError, CalculationParameters


try:
    # Both method and parameters is invalid
    params = CalculationParameters(method=None, fajr_angle=18)
    # ... but passing both to PrayerTimes raises
except ConfigurationError as e:
    print(f"Invalid config: {e}")

ValidationError

Section titled “ValidationError”

Raised for out-of-range input:

from alfalak import ValidationError, Coordinates


try:
    Coordinates(latitude=91, longitude=0)
except ValidationError as e:
    print(f"Invalid coordinates: {e}")

Error messages

Section titled “Error messages”

All errors include descriptive messages:

AstronomicalError: Unable to compute prayer times: sunrise, sunset, or solar transit is undefined for these coordinates and date (polar day/night). coordinates=Coordinates(latitude=78.2232, longitude=15.6267), date=DateComponents(year=2026, month=6, day=21).

See also

Section titled “See also”