lfnovo/open-notebook · error · HTTPException

Error executing transformation: {str(e)}

Error message

Error executing transformation: {str(e)}

What it means

Generic 500 raised by the POST /transformations/execute endpoint when the transformation graph (LangGraph) invocation fails with an unexpected exception. The endpoint validates the transformation and model first (404s), so a 500 here almost always originates inside transformation_graph.ainvoke — e.g. the AI provider call, prompt rendering, or output parsing.

Source

Thrown at api/routers/transformations.py:134

                input_text=execute_request.input_text,
                transformation=transformation,
            ),
            config=dict(configurable={"model_id": model_id}),
        )

        return TransformationExecuteResponse(
            output=result["output"],
            transformation_id=execute_request.transformation_id,
            model_id=model_id,
        )

    except HTTPException:
        raise
    except OpenNotebookError:
        raise  # Let global exception handlers return proper status codes
    except Exception as e:
        logger.error(f"Error executing transformation: {str(e)}")
        raise HTTPException(
            status_code=500, detail=f"Error executing transformation: {str(e)}"
        )


@router.get("/transformations/default-prompt", response_model=DefaultPromptResponse)
async def get_default_prompt():
    """Get the default transformation prompt."""
    try:
        default_prompts: DefaultPrompts = await DefaultPrompts.get_instance()  # type: ignore[assignment]

        return DefaultPromptResponse(
            transformation_instructions=default_prompts.transformation_instructions
            or ""
        )
    except HTTPException:
        raise
    except OpenNotebookError:
        raise

View on GitHub (pinned to a7de90d38a)

Solutions

  1. Check the API server logs — the original exception message is logged via logger.error right before the 500 is raised
  2. Verify the model's provider credentials (API key env var) and that the model name is valid for that provider
  3. Test the same transformation with a small input text and the default model via /transformations/execute to isolate prompt vs provider issues
  4. If the provider is rate limiting, retry after backoff or switch the transformation to another model_id

Example fix

// before
result = await client.post('/transformations/execute', json=req)
result.raise_for_status()
// after
result = await client.post('/transformations/execute', json=req)
if result.status_code == 500:
    detail = result.json().get('detail', '')
    if 'rate limit' in detail.lower():
        await asyncio.sleep(30)
        result = await client.post('/transformations/execute', json=req)
    else:
        raise RuntimeError(f'Transformation failed: {detail}')
Defensive patterns

Strategy: try-catch

Validate before calling

resp = await client.get(f'/transformations/{req["transformation_id"]}')
assert resp.status_code == 200, 'transformation missing'
if req.get('model_id'):
    assert (await client.get(f'/models/{req["model_id"]}')).status_code == 200, 'model missing'

Try / catch

try:
    out = await client.post('/transformations/execute', json=req)
except httpx.TransportError:
    # network-level failure, safe to retry
    raise
if out.status_code >= 500:
    detail = out.json().get('detail', '')
    if 'rate' in detail.lower():
        await retry_with_backoff(req)
    else:
        raise RuntimeError(detail)

Prevention

When it happens

Trigger: POST /api/transformations/execute with a valid transformation_id and model_id where the underlying LLM provider errors (bad API key, rate limit, model name not available on the provider), or where the transformation's prompt produces unparseable output in the graph.

Common situations: Provider API key missing/expired in environment, provider quota exhausted, transformation bound to a model whose provider credentials were rotated, or a malformed transformation prompt that crashes the graph node.

Related errors

AI-assisted analysis of lfnovo/open-notebook@a7de90d38a (2026-08-27). Data as JSON: /api/errors/ef53a3bd8c140087. Report an issue: GitHub.