Logging and Debugging

Enable verbose logging, inspect HTTP requests, and diagnose common SDK errors.

When the SDK does something unexpected, the fastest way to figure out why is usually to look at the underlying HTTP request and response.

Enable verbose request logging

The SDK uses Python's standard logging module and the requests library underneath. To see every HTTP request the SDK makes:

import logging
import http.client as http_client

http_client.HTTPConnection.debuglevel = 1
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("urllib3").setLevel(logging.DEBUG)
logging.getLogger("urllib3").propagate = True

This prints each request line, headers (redacted where the SDK redacts them), and the response status. Run a single SDK call with this enabled and you'll see exactly what's being sent.

Inspect a single failing call

If you want to inspect one call without enabling global logging, drop into the adapter directly. Every high-level method on Workspace / Project / Version ultimately calls a function in roboflow.adapters.rfapi (or deploymentapi, vision_events_api); calling those directly returns the raw response and skips any post-processing the high-level method does:

from roboflow.adapters import rfapi

response = rfapi.get_workflow("YOUR_API_KEY", workspace_url="my-workspace", workflow_url="slow-webhooks")
print(response)

If the high-level call raised, the same adapter call usually raises a RoboflowError whose string is the server's verbatim response body - useful for diagnosing bad-request errors that the high-level method might wrap.

Common errors

RoboflowError: 401

Authentication failure. Either:

• ROBOFLOW_API_KEY isn't set, or

• the key passed to Roboflow(api_key=...) is wrong, or

• the key is valid but doesn't carry the scope required by the operation. See Scoped API Keys.

RoboflowError: 404

Resource not found. Check that the workspace / project / version slug matches what's in the URL bar of the web app - slugs don't always match the display name, and the SDK uses slugs throughout.

RoboflowError: 423 Locked

The workspace is in a billing-paused state. Resolve in the web app's billing page or contact support.

RuntimeError from restore()

The item isn't currently in Trash. Either it was already permanently cleaned up after the 30-day retention window, or it's still active in the workspace.

Slow uploads

Workspace.upload_dataset() defaults to num_workers=10. For large datasets, raise this (up to ~25 - beyond that you start seeing throttled responses). For the opposite case (constrained networks or shared infra), drop it.

ImportError on roboflow-slim

roboflow-slim omits Pillow, NumPy, OpenCV, and Matplotlib. If you import from roboflow.models.* or call a .predict(...).save(...)-style visualization helper, install the full roboflow package instead.

Where to look in the source

If a stack trace points into roboflow.core.workspace.py or roboflow.adapters.rfapi, the GitHub source is searchable and the methods are short. For a method's exact signature, the adapter docstrings are the source of truth.

Reporting a bug

When opening an issue at github.com/roboflow/roboflow-python, include:

• roboflow.__version__

• The Python version you're on

• The minimal reproduction (with the API key redacted)

• The full traceback or the verbose-logging output described above

Issues that include the HTTP request / response are usually fixable in one round-trip; issues that don't often need a follow-up to gather them.