How to handle a ValueError in Python

ValueError is one of those Python exceptions you will encounter early and often. It usually pops up when a function receives the right type of argument but an invalid value. Think parsing user input, converting strings to numbers, or validating data coming from APIs and forms.

Hi all,
I keep running into ValueError when parsing user input and external data in my Python app. Examples include int(“abc”), converting dates, and validating parameters for image processing tasks. I want to catch and handle ValueError without masking real bugs and also ensure I return helpful error messages to API clients.

Specifically: How to handle a ValueError in Python in a clean, maintainable way? What are practical patterns for validation, exception chaining, logging, and testing? Any examples for parameter validation when building URLs or doing media processing would be great.

A ValueError means that whatever operation you’re trying to do (converting a string to an integer, trying to add an integer to a string, passing a value to an argument) isn’t using the right data type. This issue can be pretty common for newer developers, but even seasoned devs can run into this thanks to Python’s lack of static data typing. Thankfully, it can be a pretty easy fix–granted that you catch it early.

• Type conversions that fail, like trying to convert a string to an integer
• Parsing dates, UUIDs, or enums
• Out-of-range values such as negative sizes, zero division parameters, invalid indices
• Misconfigured settings passed as strings from env or config files

def parse_positive_int(value, name="value"):
    try:
        num = int(value)
    except ValueError as e:
        # Preserve context with exception chaining
        raise ValueError(f"{name} must be an integer. Got: {value!r}") from e

    if num <= 0:
        raise ValueError(f"{name} must be > 0. Got: {num}")

    return num

def handler(data):
    # Validate early, fail fast
    width = parse_positive_int(data.get("width"), name="width")
    height = parse_positive_int(data.get("height"), name="height")
    return {"w": width, "h": height}Code language: PHP (php)

import logging

def process_payload(payload):
    try:
        size = parse_positive_int(payload["size"], "size")
    except KeyError:
        # Wrong exception type for missing keys
        raise ValueError("Missing 'size' field")
    except ValueError as e:
        logging.warning("Invalid 'size' in payload: %s", e)
        # Re-raise or return a user-facing message
        raise
    else:
        # Runs only if no exception occurred
        return {"ok": True, "size": size}
    finally:
        # Cleanup if needed
        logging.debug("process_payload finished")Code language: PHP (php)

• Validate inputs at boundaries. Check ranges, allowed sets, and formats before deeper logic.
• Use clear error messages. Include the parameter name and offending value.
• Preserve context with raise ... from e. This keeps the original traceback visible.
• Log at the right level. Use logging.exception in unexpected paths you plan to investigate.
• Convert to domain errors at boundaries. For web apps, map ValueError to a 400 response

import pytest

def test_parse_positive_int_rejects_non_int():
    with pytest.raises(ValueError):
        parse_positive_int("abc", "width")

def test_parse_positive_int_rejects_non_positive():
    with pytest.raises(ValueError):
        parse_positive_int("-10", "width")Code language: JavaScript (javascript)

When you are saving or transforming images in Python, it is common to validate file paths, sizes, and formats before acting. If you are dealing with local processing and file writes, review patterns like buffered writes and atomic saves to avoid partial outputs. See approaches in 6 ways to save images in Python and validate before writing.

For string encodings and conversions, especially around request payloads and caching, Base64 handling is a frequent source of ValueError. Validate input length and characters before decoding. For deeper context, see this overview of image conversion to Base64 in Python.

# Example with FastAPI
from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.post("/resize")
def resize(payload: dict):
    try:
        w = parse_positive_int(payload.get("w"), "w")
        h = parse_positive_int(payload.get("h"), "h")
    except ValueError as e:
        # Translate to a 400
        raise HTTPException(status_code=400, detail=str(e))
    return {"w": w, "h": h}Code language: PHP (php)

If you generate or deliver images via URLs, keep parameter validation strict to avoid malformed links and wasted requests. For example, validate width, height, and format before building an image URL.

# Example using Cloudinary's Python SDK
import cloudinary
import cloudinary.uploader

cloudinary.config(cloud_name="demo", api_key="key", api_secret="secret")

ALLOWED_FORMATS = {"jpg", "png", "webp"}

def upload_with_transform(path, width, fmt):
    # Validate before calling SDK
    width = parse_positive_int(width, "width")
    if fmt not in ALLOWED_FORMATS:
        raise ValueError(f"fmt must be one of {sorted(ALLOWED_FORMATS)}. Got: {fmt!r}")

    try:
        res = cloudinary.uploader.upload(
            path,
            transformation=[{"width": width, "crop": "scale", "fetch_format": fmt}]
        )
    except Exception as e:
        # Wrap unexpected SDK or network errors
        raise RuntimeError("Upload or transform failed") from e

    return res["secure_url"]Code language: PHP (php)

This pattern validates early, raises helpful ValueError messages for clients, and cleanly distinguishes validation errors from operational failures. 

• Validate inputs at boundaries and raise ValueError with clear messages.
• Use try-except with exception chaining to preserve context.
• Log unexpected paths and convert ValueError to 400 responses in APIs.
• When building media URLs or uploads, validate size and format before calling external services for cleaner failures and fewer retries.

• PNG to WebP Converter
• Image Upscaling and Quality Enhancement
• Image to JPG Converter
• WebM Converter

Create your free Cloudinary account and streamline your image and video workflow from upload to delivery.