Structured outputs seems to be flaky

[8lank]

After working for a while with the Claude Agent SDK, I've noticed some flakiness around structured outputs:

In many cases, when working with large data outputs, it seems that Claude is sometimes calling its internal tool StructuredOutput with a string that contains the object instead of the actual object. It then keeps looping to try to understand why the tool call is failing.

Example of StructuredOutput tool calls with different values for a same query:

Valid:

input={
  'description': "A 3-4 day family backpacking adventure ...",
  'plan': [
    {'title': 'Research and select trail options', ...},
    {'title': 'Apply for permits and finalize route', ...},
    ...
  ],
  'status': 'open',
  'summary': 'A transformative family backpacking journey...',
  'title': 'Pacific Northwest Family Backpacking Adventure'
}

Invalid:

input={
  'description': '{\n  "title": "Pacific Northwest Family Backpacking Adventure",\n  "summary": "...",\n  "description": "...",\n  "status": "open",\n  "plan": [ ... ]\n}'
}

Is this something that has been seen internally as well? Is there any plan to improve this?

[8lank]

Seems that structured outputs are still in Beta in the API (https://platform.claude.com/docs/en/build-with-claude/structured-outputs), any guidance to enable it in the SDK?

[anujhydrabadi]

Faced the same thing. In my case, it wraps the expected valid json object around a {"properties" : {}}, or a {"paramaters" : {}} block, when calling the StructuredOutput tool - eventually ending with a error_max_structured_output_retries response. This happens when the conversation has been a long one. For smaller ones, it seems to be working fine consistently.

[vishaltandale00]

i'm noticing difference in structured output across different machines types. On MacOS M4 structured output works consistently, but on Linux/X86_64 ECS container it consistently fails. I fixed this issue once by comparing the differnce in the subprocess CLI arguements, but it has come up again now after working for a month.

[lss233]

I’ve been running into this issue quite often recently as well. I noticed that Claude frequently wraps the result inside a single "output" or "response" key, so I wrote a hook be compatible with this pattern:

def _create_structured_output_fix_hooks(
    structured_output_models: List[Type[BaseModel]]
) -> Dict[HookEvent, List[HookMatcher]]:
    """
    Create SDK hooks for fixing StructuredOutput tool inputs.
    
    Fixes cases where AI returns incorrectly formatted StructuredOutput:
    - A dict with a single key containing a JSON string
    - A dict with a single key containing a nested dict
    - A dict that doesn't match the expected model structure
    
    Args:
        structured_output_models: List of Pydantic models to validate StructuredOutput against.
                                 If empty, returns empty dict (no hooks).
    
    Returns:
        Dictionary of hook events to hook matchers (only PreToolUse), or empty dict if no models provided.
    """
    # Return empty dict if no models provided
    if not structured_output_models:
        return {}
    
    async def pre_tool_structured_output_fixer(
        input_data: Dict[str, Any],
        tool_use_id: Optional[str],
        context: Any
    ) -> Dict[str, Any]:
        """
        Fix StructuredOutput tool input by attempting to parse and validate against pydantic models.
        """
        if input_data.get('hook_event_name') != 'PreToolUse':
            return {}
        
        tool_input = input_data.get('tool_input', {})
        
        # Only process if tool_input is a dict with exactly one key
        if not isinstance(tool_input, dict) or len(tool_input) != 1:
            return {}
        
        # Get the single key and its value
        single_key = list(tool_input.keys())[0]
        single_value = tool_input[single_key]
        
        # Try to validate the entire dict first
        for model in structured_output_models:
            try:
                validated = model.model_validate(tool_input)
                # If validation succeeds, the input is already correct
                return {}
            except ValidationError:
                continue
        
        # If direct validation failed, try to fix by extracting the value
        fixed_dict = None
        
        # Case 1: Value is a string - try to parse as JSON
        if isinstance(single_value, str):
            try:
                parsed_json = json.loads(single_value)
                if isinstance(parsed_json, dict):
                    # Try to validate the parsed dict
                    for model in structured_output_models:
                        try:
                            validated = model.model_validate(parsed_json)
                            fixed_dict = parsed_json
                            logger.info(f"Fixed StructuredOutput: parsed JSON string and validated against {model.__name__}")
                            break
                        except ValidationError:
                            continue
            except (json.JSONDecodeError, TypeError):
                pass
        
        # Case 2: Value is already a dict - try to validate it directly
        elif isinstance(single_value, dict):
            for model in structured_output_models:
                try:
                    validated = model.model_validate(single_value)
                    fixed_dict = single_value
                    logger.info(f"Fixed StructuredOutput: extracted dict from key '{single_key}' and validated against {model.__name__}")
                    break
                except ValidationError:
                    continue
        
        # If we found a valid fix, return updated input
        if fixed_dict is not None:
            return {
                'hookSpecificOutput': {
                    'hookEventName': 'PreToolUse',
                    'permissionDecision': 'allow',
                    'permissionDecisionReason': 'Fixed StructuredOutput format',
                    'updatedInput': fixed_dict
                }
            }
        
        # No valid fix found, return empty (don't modify)
        return {}
    
    # Create StructuredOutput fix hook matcher
    structured_output_matcher = HookMatcher(
        matcher='StructuredOutput',
        hooks=[pre_tool_structured_output_fixer]
    )
    
    return {
        'PreToolUse': [structured_output_matcher]
    }

[qing-ant]

This appears to be the same root cause as #502, which reports the same StructuredOutput wrapping behavior — the model non-deterministically wraps the schema-conforming data inside an extra key (output, response, json, properties, parameters) instead of producing the flat object, causing schema validation failures and retry loops.

#502 has more detailed analysis and is already the canonical tracker (with #571 previously closed as a duplicate of it). Closing this in favor of #502.