TypeError
TypeError: input must be string or list
Stack trace
Traceback (most recent call last):
File "main.py", line 42, in <module>
response = client.responses.create(
File "openai/resources/responses.py", line 156, in create
raise TypeError('input must be string or list')
TypeError: input must be string or list Why it happens
The Responses API is designed for streaming request/response workflows where the input field directly maps to the LLM's raw prompt text. It expects string (single prompt) or list (multiple turns/variants), not complex objects. Passing a dict, JSON object, or other type bypasses the API's type guards because the SDK validates input types before sending to OpenAI's servers.
Detection
Add type assertion before calling client.responses.create(): assert isinstance(input_value, (str, list)), f'input must be string or list, got {type(input_value).__name__}'. Log the input value and its type in error handlers to catch misconfigurations during development.
Causes & fixes
Passing a dict/JSON object instead of a string prompt
Convert the dict to a JSON string using json.dumps() or extract the text field: input=json.dumps(your_dict) or input=your_dict.get('text', '')
Passing a NumPy array, Pandas Series, or custom object type
Convert to native Python list or string: input=list(your_array) or input=str(your_object)
Passing None or other null-like value
Provide a default fallback: input=input_value or 'default prompt' before the API call
Nested list structure (list of dicts) when API expects list of strings
Flatten to list of strings: input=[item['text'] if isinstance(item, dict) else str(item) for item in your_list]
Code: broken vs fixed
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ.get('OPENAI_API_KEY'))
# BAD: Passing a dict instead of string
user_data = {'text': 'What is AI?', 'language': 'en'}
response = client.responses.create(
model='gpt-4o-mini',
input=user_data, # TypeError: input must be string or list
)
print(response)import os
from openai import OpenAI
client = OpenAI(api_key=os.environ.get('OPENAI_API_KEY'))
# FIXED: Extract string from dict or convert to string
user_data = {'text': 'What is AI?', 'language': 'en'}
input_value = user_data.get('text') if isinstance(user_data, dict) else user_data # Extract text field
response = client.responses.create(
model='gpt-4o-mini',
input=input_value, # Now passes string
)
print(f'Response received: {response.id}')Workaround
If you must keep the dict structure, serialize it before API call: import json; input_str = json.dumps(user_data); response = client.responses.create(model='gpt-4o-mini', input=input_str). Parse the response and extract the relevant text field from the LLM output.
Prevention
Define a type-safe input preprocessor function that validates and normalizes input before API calls. Use Python type hints with TypedDict to enforce input shape at development time: from typing import Union; def prepare_input(data: Union[str, list, dict]) -> str: return data if isinstance(data, str) else (json.dumps(data) if isinstance(data, dict) else str(data)). Always run type checkers (mypy, pyright) in CI/CD to catch type mismatches before deployment.