crewAIInc/crewAI · error · ValueError

Project name '{name}' would generate invalid Python class na

Error message

Project name '{name}' would generate invalid Python class name '{class_name}'

What it means

Raised by ContextualRerankTool._run when POST https://api.contextual.ai/v1/rerank returns a non-200 status. The message embeds the HTTP status code and the raw response body, which usually identifies the cause (401 bad API key, 422 invalid model/params, 429 rate limit). Note the surrounding `except Exception` converts this into a 'Failed to rerank documents: ...' string return, so callers see a string, not an exception.

Source

Thrown at lib/cli/src/crewai_cli/create_crew.py:120

    if class_name[0].isdigit():
        raise ValueError(
            f"Project name '{name}' would generate class name '{class_name}' which cannot start with a digit"
        )

    original_name_clean = re.sub(
        r"[^a-zA-Z0-9_]", "", name.replace("_", "").replace("-", "").lower()
    )
    if (
        keyword.iskeyword(original_name_clean)
        or keyword.iskeyword(class_name)
        or class_name in ("True", "False", "None")
    ):
        raise ValueError(
            f"Project name '{name}' would generate class name '{class_name}' which is a reserved Python keyword"
        )

    if not class_name.isidentifier():
        raise ValueError(
            f"Project name '{name}' would generate invalid Python class name '{class_name}'"
        )

    if parent_folder:
        folder_path = Path(parent_folder) / folder_name
    else:
        folder_path = Path(folder_name)

    if folder_path.exists():
        if is_dmn_mode_enabled():
            raise click.ClickException(f"Folder {folder_name} already exists.")
        if not click.confirm(
            f"Folder {folder_name} already exists. Do you want to override it?"
        ):
            click.secho("Operation cancelled.", fg="yellow")
            sys.exit(0)
        click.secho(f"Overriding folder {folder_name}...", fg="green", bold=True)
        shutil.rmtree(folder_path)

View on GitHub (pinned to 754d7323be)

Solutions

Read the embedded status/text in the returned 'Failed to rerank documents: ...' string — it names the exact cause.
401: verify CONTEXTUAL_API_KEY is set, valid, and has rerank access.
422: use a supported model identifier and valid documents/metadata shapes.
429/5xx: add backoff and retry the call after a delay.

Example fix

# before
out = tool._run(query=q, documents=docs, model='contextual-rerank-v9')  # -> 'Failed to rerank documents: Reranker API returned status 404...'
# after
out = tool._run(query=q, documents=docs, model='contextual-rerank-v2')
if out.startswith('Failed to rerank'):
    raise RuntimeError(out)  # surface instead of silently treating as content

Defensive patterns

Strategy: try-catch

Validate before calling

import requests
resp = requests.get("https://api.contextual.ai/v1/datastores", headers={"authorization": f"Bearer {api_key}"}, timeout=10)
if resp.status_code == 401:
    raise SystemExit("CONTEXTUAL_API_KEY is invalid or expired")

Try / catch

out = tool._run(query=q, documents=docs, model=model)  # tool returns a string on failure
if out.startswith("Failed to rerank documents:"):
    if "status 429" in out:
        time.sleep(30); out = tool._run(query=q, documents=docs, model=model)  # retry once
    else:
        raise RuntimeError(out)

Prevention

The tool swallows exceptions and returns a 'Failed to rerank documents: ...' string — always string-check the return, don't rely on exceptions.
Validate the API key with a cheap GET before the run.
Use current model identifiers and add rate-limit backoff around rerank calls.

When it happens

Trigger: Invalid or missing CONTEXTUAL_API_KEY (401), passing an unknown model name (422), payload too large, or rate limiting (429) from requests.post(rerank_url, json=payload, timeout=30).

Common situations: Expired/rotated API key, model name typo (e.g. a deprecated reranker version), bursting many rerank calls, or network egress blocked in containers.

Related errors

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