crewAIInc/crewAI · error · ValueError

You must pass oxylabs username and password when instantiati

Error message

You must pass oxylabs username and password when instantiating the tool or specify OXYLABS_USERNAME and OXYLABS_PASSWORD environment variables

What it means

Raised by OxylabsUniversalScraperTool when no Oxylabs credentials are supplied. The tool needs a username/password pair for the Oxylabs web scraping API; it looks for constructor arguments first and falls back to the OXYLABS_USERNAME and OXYLABS_PASSWORD environment variables. If neither source yields both values, this ValueError is thrown before any scraping happens.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/oxylabs_universal_scraper_tool/oxylabs_universal_scraper_tool.py:145

                        password=password,
                        sdk_type=sdk_type,
                    )
                except subprocess.CalledProcessError as e:
                    raise ImportError("Failed to install oxylabs package") from e
            else:
                raise ImportError(
                    "`oxylabs` package not found, please run `uv add oxylabs`"
                )

        if config is None:
            config = OxylabsUniversalScraperConfig()
        super().__init__(config=config, **kwargs)

    def _get_credentials_from_env(self) -> tuple[str, str]:
        username = os.environ.get("OXYLABS_USERNAME")
        password = os.environ.get("OXYLABS_PASSWORD")
        if not username or not password:
            raise ValueError(
                "You must pass oxylabs username and password when instantiating the tool "
                "or specify OXYLABS_USERNAME and OXYLABS_PASSWORD environment variables"
            )
        return username, password

    def _run(self, url: str) -> str:
        response = self.oxylabs_api.universal.scrape_url(
            url,
            **self.config.model_dump(exclude_none=True),
        )

        content = response.results[0].content

        if isinstance(content, dict):
            return json.dumps(content)

        return str(content)

View on GitHub (pinned to 754d7323be)

Solutions

Set both environment variables: export OXYLABS_USERNAME=... and export OXYLABS_PASSWORD=..., then rerun
Pass credentials explicitly: OxylabsUniversalScraperTool(username='...', password='...')
If using a .env file, load it before tool creation (e.g. python-dotenv load_dotenv()) and verify with os.environ.get
Check for typos/whitespace in the variable names and values (print(bool(os.environ.get('OXYLABS_USERNAME'))) to verify)

Example fix

# before
tool = OxylabsUniversalScraperTool()  # raises ValueError: no credentials

# after
import os
from crewai_tools.tools.oxylabs_universal_scraper_tool import OxylabsUniversalScraperTool

tool = OxylabsUniversalScraperTool(
    username=os.environ["OXYLABS_USERNAME"],
    password=os.environ["OXYLABS_PASSWORD"],
)

Defensive patterns

Strategy: validation

Validate before calling

import os

def has_oxylabs_creds() -> bool:
    return bool(os.environ.get("OXYLABS_USERNAME")) and bool(os.environ.get("OXYLABS_PASSWORD"))

assert has_oxylabs_creds(), "Set OXYLABS_USERNAME and OXYLABS_PASSWORD before creating the tool"

Try / catch

try:
    tool = OxylabsUniversalScraperTool(username=u, password=p)
except ValueError as e:
    if "OXYLABS" in str(e):
        raise SystemExit("Missing Oxylabs credentials: export OXYLABS_USERNAME/OXYLABS_PASSWORD") from e
    raise

Prevention

Export both env vars in shell profile or CI secrets
Pass credentials as constructor args in scripts so they never depend on ambient env
Fail fast at startup with an env-var check instead of at tool construction inside agent loops
Never hardcode credentials; use a secrets manager or env file that is definitely loaded

When it happens

Trigger: Instantiating OxylabsUniversalScraperTool() without username/password arguments while OXYLABS_USERNAME or OXYLABS_PASSWORD (or both) is unset or empty in the environment. The check happens in _get_credentials_from_env, which is called during setup when explicit credentials are absent.

Common situations: Running in a new shell/CI container where the env vars were never exported, setting only one of the two variables, misspelling the variable names, or passing credentials via a .env file that the process never loaded.

Related errors

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/aab5d21141e67e5d. Report an issue: GitHub.