firecrawl/firecrawl · error · ValueError

json format must be an object with 'type', 'prompt', and 'sc

Error message

json format must be an object with 'type', 'prompt', and 'schema' fields

What it means

Error "json format must be an object with 'type', 'prompt', and 'schema' fields" thrown in firecrawl/firecrawl.

Source

Thrown at apps/python-sdk/firecrawl/v2/utils/validation.py:382

    # Already a dict or unsupported type
    return schema if isinstance(schema, dict) else None


def _validate_json_format(format_obj: Any) -> Dict[str, Any]:
    """
    Validate and prepare json format object.
    
    Args:
        format_obj: Format object that should be json type
        
    Returns:
        Validated json format dict
        
    Raises:
        ValueError: If json format is missing required fields
    """
    if not isinstance(format_obj, dict):
        raise ValueError("json format must be an object with 'type', 'prompt', and 'schema' fields")
    
    if format_obj.get('type') != 'json':
        raise ValueError("json format must have type='json'")
    
    # prompt is optional in v2; only normalize when present
    # schema is recommended; if provided, normalize Pydantic forms
    schema = format_obj.get('schema')
    normalized = dict(format_obj)
    if schema is not None:
        normalized_schema = _normalize_schema(schema)
        if normalized_schema is not None:
            # Handle schema reference resolution similar to TypeScript implementation
            if isinstance(normalized_schema, dict):
                defs = normalized_schema.get("$defs", {})
                import json
                schema_string = json.dumps(normalized_schema)
                has_any_refs = (
                    normalized_schema.get("$defs") or

View on GitHub (pinned to 656bffcc28)

When it happens

Trigger: Thrown at apps/python-sdk/firecrawl/v2/utils/validation.py:382 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of firecrawl/firecrawl@656bffcc28 (2026-08-12). Data as JSON: /api/errors/74d03cd2ef7034cc. Report an issue: GitHub.