Skip to content

Clarify UV_HTTP_TIMEOUT format in error message #16940

@wrp

Description

@wrp

Feature Request: Clarify UV_HTTP_TIMEOUT format in error message

Problem

The error message for network timeouts is misleading about the expected format:

Failed to download distribution due to network timeout.
Try increasing UV_HTTP_TIMEOUT (current value: 30s).

This suggests users should set values like 120s or 180s, but the actual required format is a plain integer representing seconds.

Current Behavior

Error message shows:

current value: 30s

Users naturally try:

export UV_HTTP_TIMEOUT=120s  # Doesn't work

But must use:

export UV_HTTP_TIMEOUT=120  # Correct - integer seconds

Proposed Solution

Option 1: Clarify the error message (recommended)

Failed to download distribution due to network timeout (30s).
Try increasing UV_HTTP_TIMEOUT to a larger integer value (in seconds).
Example: export UV_HTTP_TIMEOUT=120

Option 2: Support duration suffixes

Accept values with suffixes:

  • 120 or 120s (seconds)
  • 2m (minutes = 120 seconds)

This follows common CLI conventions (Docker timeout flags, curl --max-time, etc.)

Impact

The misleading format causes user confusion - the error displays 30s which implies the s suffix is part of the format, leading users to try UV_HTTP_TIMEOUT=120s which fails.

Environment

  • uv version: (latest as of 2025-11-29)
  • OS: Multiple (affects all platforms)

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions