FoundationAgents/MetaGPT · error · ValueError

Missing necessary parameters.

Error message

Missing necessary parameters.

What it means

text_to_image requires either a MetaGPT text-to-image endpoint (config.metagpt_tti_url) or an OpenAI LLM configuration (config.get_openai_llm()); if both are absent it raises ValueError('Missing necessary parameters.'), because there is no provider left to generate the image.

Source

Thrown at metagpt/learn/text_to_image.py:38

async def text_to_image(text, size_type: str = "512x512", config: Optional[Config] = None):
    """Text to image

    :param text: The text used for image conversion.
    :param size_type: If using OPENAI, the available size options are ['256x256', '512x512', '1024x1024'], while for MetaGPT, the options are ['512x512', '512x768'].
    :param config: Config
    :return: The image data is returned in Base64 encoding.
    """
    config = config if config else Config.default()
    image_declaration = "data:image/png;base64,"

    model_url = config.metagpt_tti_url
    if model_url:
        binary_data = await oas3_metagpt_text_to_image(text, size_type, model_url)
    elif config.get_openai_llm():
        llm = LLM(llm_config=config.get_openai_llm())
        binary_data = await oas3_openai_text_to_image(text, size_type, llm=llm)
    else:
        raise ValueError("Missing necessary parameters.")
    base64_data = base64.b64encode(binary_data).decode("utf-8")

    s3 = S3(config.s3)
    url = await s3.cache(data=base64_data, file_ext=".png", format=BASE64_FORMAT)
    if url:
        return f"![{text}]({url})"
    return image_declaration + base64_data if base64_data else ""

View on GitHub (pinned to 11cdf466d0)

Solutions

1. Set config.metagpt_tti_url (env METAGPT_TTI_URL) to a MetaGPT text-to-image service endpoint.
2. Or add a valid OpenAI entry to the LLM config so config.get_openai_llm() returns one.
3. If image generation is optional for your agent, disable the actions that call promote()/text_to_image.

Example fix

# before: no TTI url, no openai entry -> ValueError
# after (option 1)
export METAGPT_TTI_URL="https://your-tti-service/api"
# after (option 2, config2.yaml)
llm:
  api_type: openai
  base_url: https://api.openai.com/v1
  api_key: YOUR_KEY
  model: gpt-4o-mini

from metagpt.config2 import config

def tti_available() -> bool:
    return bool(config.metagpt_tti_url) or bool(config.get_openai_llm())

if not tti_available():
    disable_image_actions = True

try:
    md = await text_to_image(prompt)
except ValueError as e:
    if "Missing necessary parameters" in str(e):
        md = prompt  # degrade to plain text instead of crashing the agent
    else:
        raise

When it happens

Trigger: Calling text_to_image/promote() when neither METAGPT_TTI_URL is set nor a valid OpenAI model entry (api key etc.) exists in the LLM configuration.

Common situations: Running agents with non-OpenAI providers only (e.g. Azure/Anthropic entries) and then triggering an action that renders an image; missing env vars METAGPT_TTI_URL / OPENAI_API_KEY in deployment; config2.yaml not enabling the openai entry.

Related errors

• use `review` after `fill`
• please check MilvusConnection, uri must be set.
• please check QdrantConnection.
• Rollouts must be greater than 2 if there is no tree to load
• Error loading configuration for model '{model}': {str(e)}

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/2cef19ff4b7563b7. Report an issue: GitHub.