apache/seatunnel · error · ValueError

ORCAROUTER_API_KEY environment variable is required for…

Error message

ORCAROUTER_API_KEY environment variable is required for AI_PROVIDER=orcarouter

What it means

The OrcaRouter provider requires an API key supplied through the ORCAROUTER_API_KEY environment variable. __init__ raises ValueError when the variable is unset or empty, because no authenticated requests can be made without it.

Solutions

Export the key: export ORCAROUTER_API_KEY=<your-key> in the shell running seatunnel
Persist the variable in ~/.bashrc, ~/.zshrc, or an .env file loaded by the runner
Alternatively run `seatunnel --init` interactive setup to store credentials
In CI, add ORCAROUTER_API_KEY as a secret environment variable

Example fix

// before
$ AI_PROVIDER=orcarouter seatunnel chat
ValueError: ORCAROUTER_API_KEY environment variable is required...
// after
$ export ORCAROUTER_API_KEY=sk-orca-...
$ seatunnel chat

Defensive patterns

Strategy: validation

Validate before calling

import os
assert os.environ.get("ORCAROUTER_API_KEY"), "Set ORCAROUTER_API_KEY before running"

Try / catch

try:
    provider = create_provider("orcarouter")
except ValueError as e:
    if "ORCAROUTER_API_KEY" in str(e):
        print("Export ORCAROUTER_API_KEY first")
        sys.exit(1)
    raise

Prevention

Export ORCAROUTER_API_KEY in shell startup files or an .env loaded by the runner
Add the key as a secret in CI pipelines
Check env presence with a preflight script before launching long jobs

When it happens

Trigger: Constructing the orcarouter provider while os.environ.get("ORCAROUTER_API_KEY") returns None/empty — i.e. AI_PROVIDER=orcarouter is set (or provider name passed explicitly) but the key env var was never exported in the current shell/session.

Common situations: Setting AI_PROVIDER in a config file but exporting the key only in another shell; forgetting the export after installing the package; CI jobs missing the secret; running under systemd/cron where interactive shell env vars don't propagate.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/7423d5b825268a2e. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-cli/seatunnel_cli/llm_provider.py:1286

    """

    #: OrcaRouter's OpenAI-compatible base URL.
    DEFAULT_BASE_URL = "https://api.orcarouter.ai/v1"
    #: Default model: auto-routes to the best model for the request.
    DEFAULT_MODEL = "orcarouter/auto"

    def __init__(self):
        try:
            import openai
        except ImportError:
            raise ImportError(
                "openai package required for AI_PROVIDER=orcarouter. "
                "Install it: pip install openai"
            )

        api_key = os.environ.get("ORCAROUTER_API_KEY")
        if not api_key:
            raise ValueError(
                "ORCAROUTER_API_KEY environment variable is required for "
                "AI_PROVIDER=orcarouter"
            )

        self._model_id = os.environ.get(
            "ORCAROUTER_MODEL",
            os.environ.get("OPENAI_MODEL", self.DEFAULT_MODEL))
        self._fast_model_id = os.environ.get(
            "ORCAROUTER_SMALL_FAST_MODEL",
            os.environ.get("OPENAI_SMALL_FAST_MODEL", self._model_id))
        self._client = openai.OpenAI(api_key=api_key, base_url=self.DEFAULT_BASE_URL)
        self._echo_reasoning_content = _env_bool(
            "ORCAROUTER_ECHO_REASONING_CONTENT", True)

    @property
    def provider_name(self) -> str:
        return "orcarouter"

View on GitHub (pinned to cf67b549a7)