[OPIK-5359] [BE] [SDK] fix: improve pairing code error messages and CLI URL logging by JetoPistola · Pull Request #5979 · comet-ml/opik

JetoPistola · 2026-03-30T20:38:38Z

Details

Improve error messages when opik connect --pair fails, to help users diagnose environment mismatch issues. Currently the error "Invalid or expired pairing code" is unhelpful — it doesn't indicate which backend was targeted or why the code wasn't found.

This PR will:

SDK: Include the backend URL in CLI error output when pairing fails
BE: Distinguish between code-not-found, expired, and already-consumed failure modes

Architecture / Flow Diagram

┌─────────────────────────────────────────────────────────────────────────┐
│                        PAIRING CODE FLOW                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────┐    POST /v1/private/          ┌──────────────┐            │
│  │  Opik UI  │──── local-runners/pair ──────▶│   Backend    │            │
│  │ (Browser) │                               │  (Java API)  │            │
│  └──────────┘                               └──────┬───────┘            │
│                                                     │                    │
│                                              Generate 6-char code        │
│                                              Store in Redis:             │
│                                              key: opik:runners:pair:{CODE}│
│                                              TTL: 300s                   │
│                                                     │                    │
│                                              ┌──────▼───────┐            │
│                                              │    Redis      │            │
│                                              │  (env-specific)│           │
│                                              └──────▲───────┘            │
│                                                     │                    │
│  ┌──────────┐    POST /v1/private/          ┌──────┴───────┐            │
│  │   CLI    │──── local-runners/            │   Backend    │            │
│  │ (opik   │     connections                │  (Java API)  │            │
│  │ connect) │◀──────────────────────────────│              │            │
│  └──────────┘                               └──────────────┘            │
│       │                                                                  │
│       │  URL resolved from:                                              │
│       │  1. Passed values                                                │
│       │  2. Session config                                               │
│       │  3. OPIK_URL_OVERRIDE env var                                    │
│       │  4. ~/.opik.config                                               │
│       │  5. Default: https://www.comet.com/opik/api/ (PROD)              │
│       │                                                                  │
├───────┴──────────────────────────────────────────────────────────────────┤
│                     ⚠️  THE PROBLEM                                      │
│                                                                          │
│  If UI generates code on TEST env Redis, but CLI hits PROD backend       │
│  (different Redis) → code doesn't exist → "Invalid or expired"           │
│                                                                          │
│  ┌─────────┐         ┌──────────────┐     ┌──────────────┐              │
│  │ TEST UI │──code──▶│ TEST Redis   │     │ PROD Redis   │◀── CLI hits  │
│  └─────────┘         │ (has code)   │     │ (no code!)   │    here      │
│                      └──────────────┘     └──────────────┘              │
├──────────────────────────────────────────────────────────────────────────┤
│                     🔧 PROPOSED CHANGES                                  │
│                                                                          │
│  SDK (connect.py):                                                       │
│  ┌──────────────────────────────────────────────────────────────────┐    │
│  │ except ApiError as e:                                            │    │
│  │-    click.echo(f"Error: {e.body}")                               │    │
│  │+    click.echo(f"Error: {e.body} (targeting {config.url})")      │    │
│  └──────────────────────────────────────────────────────────────────┘    │
│                                                                          │
│  Backend (LocalRunnerService.java):                                      │
│  ┌──────────────────────────────────────────────────────────────────┐    │
│  │  claimPairingCode():                                             │    │
│  │  - Add logging: code attempted, Redis key queried                │    │
│  │  - Consider: get() before getAndDelete() to distinguish          │    │
│  │    "never existed" vs "expired" vs "already consumed"            │    │
│  └──────────────────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────────────────┘

Change checklist

User facing
Documentation update

Issues

OPIK-5359

AI-WATERMARK

AI-WATERMARK: yes

Tools: Claude Code
Model(s): Claude Opus 4.6
Scope: PR setup and planning
Human verification: code review pending

Testing

No code changes yet — this is a draft PR for implementation planning.

Documentation

N/A — will update if CLI help text changes.

…LI URL logging Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ages

github-actions · 2026-03-31T13:57:25Z

🔄 Test environment deployment process has started

Phase 1: Deploying base version 1.10.57-4756 (from main branch) if environment doesn't exist
Phase 2: Building new images from PR branch danield/OPIK-5359-improve-pairing-error-messages
Phase 3: Will deploy newly built version after build completes

You can monitor the progress here.

CometActions · 2026-03-31T14:06:20Z

✅ Test environment is now available!

To configure additional Environment variables for your environment, run [Deploy Opik AdHoc Environment workflow] (https://github.com/comet-ml/comet-deployment/actions/workflows/deploy_opik_adhoc_env.yaml)