{"record":{"id":"ce8defdb4c407af1","repo":"microsoft/semantic-kernel","slug":"unresolved-placeholders-in-spec-join-f-ce8def","errorCode":null,"errorMessage":"Unresolved placeholders in spec: {', '.join(f'${{{key}}}' for key in unresolved)}","messagePattern":"Unresolved placeholders in spec: (.+?)\\}' for key in unresolved\\)\\}","errorType":"exception","errorClass":"AgentInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/open_ai/azure_responses_agent.py","lineNumber":289,"sourceCode":"        if extras:\n            field_mapping.update(extras)\n\n        def replacer(match: re.Match[str]) -> str:\n            \"\"\"Replace the matched placeholder with the corresponding value from field_mapping.\"\"\"\n            full_key = match.group(1)  # for example, AzureOpenAI:ApiKey\n            section, _, key = full_key.partition(\":\")\n            if section != \"AzureOpenAI\":\n                return match.group(0)\n\n            # Try short key first (ApiKey), then full (AzureOpenAI:ApiKey)\n            return str(field_mapping.get(key) or field_mapping.get(full_key) or match.group(0))\n\n        result = pattern.sub(replacer, yaml_str)\n\n        # Safety check for unresolved placeholders\n        unresolved = pattern.findall(result)\n        if unresolved:\n            raise AgentInitializationException(\n                f\"Unresolved placeholders in spec: {', '.join(f'${{{key}}}' for key in unresolved)}\"\n            )\n\n        return result\n","sourceCodeStart":271,"sourceCodeEnd":294,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/open_ai/azure_responses_agent.py#L271-L294","documentation":"Raised by AzureResponsesAgent.resolve_placeholders() after substitution when one or more ${AzureOpenAI:Key} placeholders remain unresolved. A placeholder is unresolved when its key is absent from both the settings-derived field_mapping (ChatModelId, AgentId, ApiKey, ApiVersion, BaseUrl, Endpoint, TokenEndpoint) and the extras dict.","triggerScenarios":"A declarative spec contains a placeholder referencing a key that is not in the built-in mapping and not supplied via extras (e.g. ${AzureOpenAI:Region}), or the corresponding settings field is empty so the value falls back to the literal placeholder.","commonSituations":"Typos in placeholder keys; referencing fields outside the supported mapping; forgetting to pass runtime values via extras; spec files not updated after a schema change.","solutions":["Read the unresolved keys in the error and correct/remove them in the spec.","Supply missing values through extras: resolve_placeholders(yaml, extras={'Key': value}).","Ensure mapped settings fields are populated (e.g. set AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME for ChatModelId).","Restrict placeholders to the supported key set."],"exampleFix":"# before\nAzureResponsesAgent.resolve_placeholders(yaml)  # yaml has ${AzureOpenAI:Region}\n# after (remove placeholder, or supply)\nAzureResponsesAgent.resolve_placeholders(yaml, extras={\"Region\": \"eastus\"})","handlingStrategy":"validation","validationCode":"import re\n\nSUPPORTED = {\"ChatModelId\", \"AgentId\", \"ApiKey\", \"ApiVersion\", \"BaseUrl\", \"Endpoint\", \"TokenEndpoint\"}\nplaceholders = set(re.findall(r\"\\$\\{AzureOpenAI:([^}]+)\\}\", yaml_str))\nunknown = placeholders - SUPPORTED - set(extras or {})\nif unknown:\n    raise ValueError(f\"Unsupported/unsupplied placeholders: {unknown}\")\nresolved = AzureResponsesAgent.resolve_placeholders(yaml_str, settings=settings, extras=extras)","typeGuard":null,"tryCatchPattern":"from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException\n\ntry:\n    resolved = AzureResponsesAgent.resolve_placeholders(yaml_str, extras=extras)\nexcept AgentInitializationException as e:\n    missing = parse_unresolved(e.args[0])\n    extras = extras or {}\n    extras.update(resolve_from_env(missing))\n    resolved = AzureResponsesAgent.resolve_placeholders(yaml_str, extras=extras)","preventionTips":["Keep a canonical list of supported placeholder keys and lint specs.","Supply runtime values via extras, not invented settings fields.","Test spec rendering in CI."],"tags":["azure-openai","declarative-spec","semantic-kernel","agents","placeholders","validation"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}