Skip to content

fix: clear errors for connection, auth, and API failures#28

Merged
jpetey75 merged 1 commit into
mainfrom
fix/clearer-connection-errors
Jun 26, 2026
Merged

fix: clear errors for connection, auth, and API failures#28
jpetey75 merged 1 commit into
mainfrom
fix/clearer-connection-errors

Conversation

@jpetey75

@jpetey75 jpetey75 commented Jun 26, 2026

Copy link
Copy Markdown
Contributor

Closes #1

Problem

A misconfigured client surfaced a raw, Lightdash-agnostic error that gave no hint at the cause:

client = Client(instance_url="https://app.lightdash.com", access_token="xxxx", project_uuid="xxxx")
client.list_models()
# httpx.ConnectError: [Errno 8] nodename nor servname provided, or not known

Change (intentionally minimal)

A nested try around just the request translates the two reported failure modes into clear, catchable exceptions. The existing raise_for_status + structured-error handling is left completely untouched (unchanged context in the diff):

Failure Exception Message
DNS / refused connection / timeout LightdashConnectionError names instance_url + likely cause
HTTP 401 / 403 LightdashAuthError points at the access_token

Both subclass LightdashError, so existing except LightdashError handlers keep working, and the original httpx error is chained as __cause__.

Production diff is +61/−9 across 3 files; client.py is +37/−9, all additive around the request — no change to the success path or the existing API-error path.

Scope note: an earlier revision also reworked the 4xx/5xx path to surface the API's message on HTTP errors. That changed existing behaviour, so it was cut from this PR to keep it small; it can be a separate change later if wanted.

Verified live (the issue's two exact cases)

CONNECT -> LightdashConnectionError (0): Could not connect to Lightdash at
           https://this-host-does-not-exist.invalid. Check that instance_url is correct...
AUTH    -> LightdashAuthError (401): Authentication failed (HTTP 401) for
           https://analytics.lightdash.cloud. Check that your access_token is valid...

Tests

tests/test_client_errors.py (8): connect-error wrapping, timeout wrapping, LightdashError subclassing, cause-chaining, 401/403 → auth error, plus two guard tests that the existing structured-error and success paths are unchanged. Full unit suite green (131 passed).

A misconfigured client surfaced a raw httpx error that never mentioned
Lightdash (e.g. `httpx.ConnectError: nodename nor servname provided`).

`_make_request` now translates the two reported failure modes into descriptive,
catchable exceptions — without touching the existing API-error handling:

- Transport failures (DNS, refused connection, timeout) -> LightdashConnectionError,
  naming instance_url and the likely cause.
- HTTP 401/403 -> LightdashAuthError, pointing at the access_token.

Both subclass LightdashError so existing handlers keep working, and the original
httpx error is chained as __cause__. The raise_for_status path and structured
error handling are unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@jpetey75 jpetey75 force-pushed the fix/clearer-connection-errors branch from 70a0b85 to 2def22d Compare June 26, 2026 20:38
@jpetey75 jpetey75 merged commit 4e9516e into main Jun 26, 2026
2 checks passed
@jpetey75 jpetey75 deleted the fix/clearer-connection-errors branch June 26, 2026 20:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Obscure error message when connection to Lightdash doesn't work

1 participant